davinci-resolve-mcp 2.51.0 → 2.52.1

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 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.52.1
+
+Analysis reuse no longer blocks on missing capabilities when every clip is
+satisfied by an existing report (issue #68). `build_plan` records
+`capability_gaps` from the *requested* options before the per-clip reuse
+decision runs; when a fully-reused plan only re-keys and imports existing
+reports into the current root, no fresh transcription/vision/ffprobe happens,
+so the missing-capability gate must not fire.
+
+- **Fixed** the missing-capability gate is now evaluated against the clips that
+  still need fresh analysis, not the requested-options gaps. A clip is exempt
+  only when it both skips execution and has an existing report path; any clip
+  needing fresh work still enforces the gate.
+- **Fixed** extended the exemption to the entry points that short-circuit
+  before `execute_plan_async` and were still blocking fully-reused runs: the
+  `media_analysis` analyze action, metadata-publish analysis, and batch-job
+  creation. The batch CLI `plan` preview no longer prints "Missing tools" for a
+  fully-reusable plan.
+- **Changed** the reuse/capability logic is now a shared
+  `plan_requires_capabilities()` / `executing_clips()` helper, replacing the
+  duplicated inline comprehensions so every gate stays consistent.
+- Includes PR #68 by @diesdaas, which fixed the inner `execute_plan_async` gate
+  and isolated the marker-param and host-vision tests from unrelated
+  capability/destructive-hook coupling.
+
+## What's New in v2.52.0
+
+`edit_engine` tighten now carries audio. Previously `execute_tighten`
+assembled a video-only variant — a speech-driven dead-air cut came out
+silent, with nothing in the preview or readback to warn you (issue #67).
+
+- **Fixed** `plan_tighten` mirrors every kept video range onto its linked
+  audio track(s) with identical source frames, so the assembled variant
+  stays frame-locked and audible. Audio targets the item's detected linked
+  audio tracks (same `GetLinkedItems` matching `execute_swap` uses), falling
+  back to audio track 1 where a single linked A/V clip's audio lives.
+- **Added** `include_audio` parameter to `plan_tighten` (default `true`).
+  Pass `include_audio=false` for the prior video-only assembly.
+- **Added** an `audio_accounting` block to the `execute_tighten` confirm
+  preview and readback (planned vs. actual audio/video item counts), so a
+  silent variant can no longer ship unnoticed. Old video-only plans
+  re-executed against this build still work and are now loudly flagged as
+  silent.
+
 ## What's New in v2.51.0
 
 CLAP audio embeddings — the final phase of the post-program improvements.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.51.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.52.1-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-34%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -722,11 +722,15 @@ clip-count readback plus `brain_edits` rationale rows.
   `execute_selects(plan_id)` creates a NEW selects timeline from the plan's
   per-shot source ranges — additive; nothing existing is touched.
 - `plan_tighten(timeline_name?, target_ratio?, min_pause_seconds?,
-  handle_seconds?)` — dead-air lifts from transcript-gap evidence for each
-  timeline item (items without transcripts are reported in `skipped`, never
-  silently trimmed). `execute_tighten(plan_id)` assembles a tightened
-  VARIANT timeline from the plan's keep ranges — true partial trims; the
-  original timeline is never mutated.
+  handle_seconds?, include_audio?)` — dead-air lifts from transcript-gap
+  evidence for each timeline item (items without transcripts are reported in
+  `skipped`, never silently trimmed). `execute_tighten(plan_id)` assembles a
+  tightened VARIANT timeline from the plan's keep ranges — true partial
+  trims; the original timeline is never mutated. v2.52.0+: kept ranges mirror
+  onto each item's linked audio track(s) so the variant is audible (a
+  speech-driven cut was previously silent — #67); pass
+  `include_audio=false` for a video-only assembly, and the
+  `execute_tighten` readback carries an `audio_accounting` block.
 - `plan_swap(timeline_start_frame | item_name, kind="visual"|"text",
   limit?)` — alternates for one timeline item via the similarity index,
   filtered to shots long enough to fill the slot exactly.

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.51.0"
+VERSION = "2.52.1"
 # 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.51.0",
+  "version": "2.52.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/batch_cli.py

@@ -17,6 +17,7 @@ from typing import Any, Dict, List, Optional
 from src.utils.media_analysis import (
     build_plan,
     detect_capabilities,
+    plan_requires_capabilities,
 )
 from src.utils.media_analysis_jobs import (
     batch_job_status,
@@ -187,7 +188,7 @@ def _cmd_plan(args: argparse.Namespace) -> int:
             f"Est. seconds : {plan.get('estimated_seconds_after_reuse', '?')}",
             json_mode=False,
         )
-        if plan.get("capability_gaps"):
+        if plan.get("capability_gaps") and plan_requires_capabilities(plan):
             _emit(f"Missing tools: {plan['capability_gaps']}", json_mode=False)
         for w in warnings:
             _emit(f"  warning: {w}", json_mode=False)

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.51.0"
+VERSION = "2.52.1"
 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.51.0"
+VERSION = "2.52.1"
 
 import base64
 import os
@@ -77,6 +77,7 @@ from src.utils.media_analysis import (
     execute_plan_async as execute_media_analysis_plan_async,
     install_guidance as media_analysis_install_guidance,
     load_report as load_media_analysis_report,
+    plan_requires_capabilities as media_analysis_plan_requires_capabilities,
     query_analysis_index,
     resolve_output_root as resolve_media_analysis_output_root,
     short_hash,
@@ -9226,7 +9227,7 @@ async def _publish_clip_metadata_from_analysis(
         )
         if not plan.get("success"):
             return plan
-        if plan.get("capability_gaps"):
+        if plan.get("capability_gaps") and media_analysis_plan_requires_capabilities(plan):
             return _media_analysis_missing_capabilities_response(plan, action_label="metadata publish analysis")
 
         manifest = await execute_media_analysis_plan_async(
@@ -16268,7 +16269,11 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
             plan["setup_defaults_applied"] = p.get("_setup_defaults_applied")
         if warnings:
             plan["warnings"] = warnings
-        if plan.get("capability_gaps") and not bool(p.get("dry_run", True)):
+        if (
+            plan.get("capability_gaps")
+            and not bool(p.get("dry_run", True))
+            and media_analysis_plan_requires_capabilities(plan)
+        ):
             return _e2_wrap(_media_analysis_missing_capabilities_response(plan))
         if not bool(p.get("dry_run", True)):
             executed = await execute_media_analysis_plan_async(
@@ -16592,6 +16597,15 @@ def _edit_engine_collect_items(tl, *, track_index: Optional[int] = None) -> List
                         pass
             except Exception:
                 pass
+            # Linked audio track indices so the planner can mirror kept ranges
+            # onto sound (see #67 — tighten variants were coming out silent).
+            try:
+                audio_indices, _audio_note = _edit_engine_linked_audio_tracks(
+                    tl, item, row["timeline_start_frame"], row["timeline_end_frame"]
+                )
+                row["audio_track_indices"] = audio_indices
+            except Exception:
+                row["audio_track_indices"] = []
             rows.append(row)
     return rows
 
@@ -16732,10 +16746,13 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
     - execute_selects(plan_id, confirm_token?) — creates a NEW selects timeline
       from the plan's clip in/out ranges. Nothing existing is touched.
     - plan_tighten(timeline_name?, target_ratio?, min_pause_seconds?,
-      handle_seconds?) — dead-air lifts from transcript-gap evidence for the
-      current (or named) timeline.
-    - execute_tighten(plan_id, confirm_token?) — duplicates the timeline and
-      applies the lifts (ripple) to the DUPLICATE, never the original.
+      handle_seconds?, include_audio?) — dead-air lifts from transcript-gap
+      evidence for the current (or named) timeline. Kept ranges mirror onto the
+      items' linked audio tracks by default so the variant is audible; pass
+      include_audio=false for a video-only (silent) assembly.
+    - execute_tighten(plan_id, confirm_token?) — assembles a tightened VARIANT
+      timeline from the plan's keep ranges (video + mirrored audio), never
+      mutating the original. Readback includes an audio_accounting block.
     - plan_swap(track_index?, timeline_start_frame | item_name, kind?, limit?)
       — alternates for one timeline item via the similarity index.
     - execute_swap(plan_id, alternate_index, confirm_token?) — replaces the
@@ -16807,6 +16824,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
             target_ratio=p.get("target_ratio") or p.get("targetRatio"),
             min_pause_seconds=float(p.get("min_pause_seconds") or p.get("minPauseSeconds") or _edit_engine_mod.DEFAULT_MIN_PAUSE_SECONDS),
             handle_seconds=float(p.get("handle_seconds") or p.get("handleSeconds") or _edit_engine_mod.DEFAULT_HANDLE_SECONDS),
+            include_audio=str(p.get("include_audio", p.get("includeAudio", True))).strip().lower() not in {"false", "0", "no", "none", "off"},
         )
 
     if action == "plan_swap":
@@ -16951,6 +16969,8 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         keep_ranges = plan.get("keep_ranges") or []
         if not keep_ranges:
             return _err("plan has no keep_ranges — re-plan with this version")
+        audio_keep_ranges = sum(1 for r in keep_ranges if str(r.get("track_type", "video")).lower() == "audio")
+        video_keep_ranges = len(keep_ranges) - audio_keep_ranges
         if "confirm_token" not in p and "confirmToken" not in p and _confirm_token_required():
             return _issue_confirm_token(
                 action="edit_engine.execute_tighten", params=p,
@@ -16963,6 +16983,13 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                     "timeline_name": plan.get("timeline_name"),
                     "lift_count": len(lifts),
                     "keep_range_count": len(keep_ranges),
+                    "video_keep_range_count": video_keep_ranges,
+                    "audio_keep_range_count": audio_keep_ranges,
+                    "audio_note": (
+                        f"Variant carries audio ({audio_keep_ranges} audio ranges mirror the video cuts)."
+                        if audio_keep_ranges
+                        else "WARNING: variant is VIDEO-ONLY (silent) — plan has no audio ranges."
+                    ),
                     "estimated_removed_seconds": sum(l.get("duration_seconds") or 0 for l in lifts),
                 },
             )
@@ -17039,6 +17066,23 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
                     else None
                 ),
                 "structural_diff": structural_diff,
+                "audio_accounting": {
+                    "planned_audio_ranges": audio_keep_ranges,
+                    "planned_video_ranges": video_keep_ranges,
+                    "variant_audio_items": sum(
+                        1 for it in (variant.get("items") or [])
+                        if (it.get("range") or {}).get("media_type") == 2
+                    ),
+                    "variant_video_items": sum(
+                        1 for it in (variant.get("items") or [])
+                        if (it.get("range") or {}).get("media_type") == 1
+                    ),
+                    "note": (
+                        "Variant carries audio mirrored from the video cuts."
+                        if audio_keep_ranges
+                        else "Variant is VIDEO-ONLY (silent) — re-plan with include_audio=True for sound."
+                    ),
+                },
             },
             "plan_id": plan.get("plan_id"),
         }

package/src/utils/edit_engine.py

@@ -348,13 +348,23 @@ def plan_tighten(
     target_ratio: Optional[float] = None,
     min_pause_seconds: float = DEFAULT_MIN_PAUSE_SECONDS,
     handle_seconds: float = DEFAULT_HANDLE_SECONDS,
+    include_audio: bool = True,
 ) -> Dict[str, Any]:
     """Propose dead-air lifts for a timeline.
 
     `items` rows come from the server (Resolve read): each needs
     {timeline_start_frame, timeline_end_frame, source_start_frame,
-     media_ref (clip id / path / hash), item_name?}. Lifts are returned in
-    timeline frames, latest-first ready.
+     media_ref (clip id / path / hash), item_name?}. Optionally each row may
+    carry {audio_track_indices: [int, ...]} naming the audio tracks that hold
+    the item's linked audio. Lifts are returned in timeline frames, latest-first
+    ready.
+
+    When ``include_audio`` (the default), each kept video range is mirrored onto
+    matching audio range(s) so the assembled variant carries sound — a
+    speech-driven cut would otherwise come out silent (see #67). Audio is
+    mirrored to the item's detected ``audio_track_indices``; absent that, it
+    falls back to audio track 1, which is where a single linked A/V clip's audio
+    lives.
     """
     if not items:
         return {"success": False, "error": "No timeline items supplied"}
@@ -475,6 +485,11 @@ def plan_tighten(
             cursor = max(cursor, lift_end_sec)
         if spec["src_end_sec"] - cursor > 0.05:
             segments.append((cursor, spec["src_end_sec"]))
+        audio_indices: List[int] = []
+        if include_audio:
+            audio_indices = [int(i) for i in (item.get("audio_track_indices") or []) if int(i) > 0]
+            if not audio_indices:
+                audio_indices = [1]
         for seg_start, seg_end in segments:
             start_frame = int(round(seg_start * clip_fps))
             end_frame = max(start_frame + 1, int(round(seg_end * clip_fps)) - 1)
@@ -485,23 +500,40 @@ def plan_tighten(
                 "track_type": "video",
                 "track_index": int(item.get("track_index") or 1),
             })
+            # Mirror each kept video range onto its linked audio track(s) with
+            # identical source frames so the variant stays frame-locked and
+            # audible. mediaType 2 pulls the same media-pool item's audio.
+            for audio_index in audio_indices:
+                keep_ranges.append({
+                    "clip_id": spec["resolve_clip_id"],
+                    "start_frame": start_frame,
+                    "end_frame": end_frame,
+                    "track_type": "audio",
+                    "media_type": 2,
+                    "track_index": audio_index,
+                })
 
     removed_frames = sum(l["timeline_end_frame"] - l["timeline_start_frame"] for l in lifts)
+    audio_keep_range_count = sum(1 for r in keep_ranges if r.get("track_type") == "audio")
+    video_keep_range_count = len(keep_ranges) - audio_keep_range_count
     plan = save_plan(project_root, {
         "kind": "tighten",
         "timeline_name": timeline_name,
         "timeline_fps": fps,
         "lifts": lifts,
         "keep_ranges": keep_ranges,
+        "include_audio": bool(include_audio),
         "skipped": skipped,
         "summary": (
             f"{len(lifts)} dead-air lifts, ~{round(removed_frames / fps, 1)}s removed "
-            f"from '{timeline_name}' (assembled as a tightened variant)"
+            f"from '{timeline_name}' (assembled as a tightened variant"
+            f"{', video + audio' if include_audio else ', video only'})"
         ),
         "settings": {
             "target_ratio": target_ratio,
             "min_pause_seconds": min_pause_seconds,
             "handle_seconds": handle_seconds,
+            "include_audio": bool(include_audio),
         },
     })
     return {
@@ -514,11 +546,20 @@ def plan_tighten(
         "estimated_removed_seconds": round(removed_frames / fps, 2),
         "lifts": lifts,
         "keep_range_count": len(keep_ranges),
+        "video_keep_range_count": video_keep_range_count,
+        "audio_keep_range_count": audio_keep_range_count,
+        "include_audio": bool(include_audio),
         "skipped": skipped,
         "note": (
             "Dry-run plan. Execute with edit_engine(action='execute_tighten', "
             "params={plan_id}) — a tightened VARIANT timeline is assembled from "
-            "the keep ranges; the original timeline is never mutated."
+            "the keep ranges; the original timeline is never mutated. "
+            + (
+                f"Audio is mirrored onto matching tracks ({audio_keep_range_count} "
+                "audio ranges) so the variant is audible."
+                if include_audio
+                else "include_audio=False: the variant will be VIDEO-ONLY (silent)."
+            )
         ),
     }
 

package/src/utils/media_analysis.py

@@ -5117,6 +5117,37 @@ async def _maybe_run_vision_analysis(
     return _vision_analysis(record, motion, options, artifacts, capabilities)
 
 
+def _clip_is_reused(clip: Any) -> bool:
+    """A clip is satisfied by an existing report and runs no fresh analysis."""
+    return bool(
+        isinstance(clip, dict)
+        and clip.get("skip_execution")
+        and (clip.get("existing_report") or {}).get("path")
+    )
+
+
+def executing_clips(plan: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Clips in ``plan`` that still require fresh analysis (not pure reuse)."""
+    return [
+        clip
+        for clip in plan.get("clips", [])
+        if isinstance(clip, dict) and not _clip_is_reused(clip)
+    ]
+
+
+def plan_requires_capabilities(plan: Dict[str, Any]) -> bool:
+    """True when at least one clip needs fresh analysis.
+
+    ``build_plan`` records ``capability_gaps`` from the *requested* options
+    before the per-clip reuse decision runs. When every clip is satisfied by an
+    existing reusable report, execution only re-keys/imports those reports into
+    the current root and performs no fresh transcription/vision/ffprobe — so the
+    missing-capability gate must not fire. Callers gate with
+    ``plan.get("capability_gaps") and plan_requires_capabilities(plan)``.
+    """
+    return bool(executing_clips(plan))
+
+
 async def execute_plan_async(
     plan: Dict[str, Any],
     params: Optional[Dict[str, Any]] = None,
@@ -5155,7 +5186,8 @@ async def execute_plan_async(
                 for clip in blocked
             ],
         }
-    if plan.get("capability_gaps"):
+    fresh_clips = executing_clips(plan)
+    if plan.get("capability_gaps") and fresh_clips:
         return {
             "success": False,
             "error": "Cannot execute analysis with missing required capabilities",
@@ -5204,17 +5236,13 @@ async def execute_plan_async(
         and vision_uses_chat_context(options, caps)
         and not _coerce_bool(params.get("confirm_deep") or params.get("confirmDeep"), default=False)
     ):
-        executing = [
-            clip for clip in plan.get("clips", [])
-            if not (clip.get("skip_execution") and (clip.get("existing_report") or {}).get("path"))
-        ]
-        estimated_frames = sum(int(c.get("analysis_keyframe_budget") or 0) for c in executing)
+        estimated_frames = sum(int(c.get("analysis_keyframe_budget") or 0) for c in fresh_clips)
         return {
             "success": True,
             "status": "confirmation_required",
             "reason": "deep_depth_cost_estimate",
             "estimate": {
-                "clip_count": len(executing),
+                "clip_count": len(fresh_clips),
                 "estimated_frames": estimated_frames,
                 "estimated_vision_tokens": estimated_frames * AVG_VISION_TOKENS_PER_FRAME,
                 "tokens_per_frame_assumption": AVG_VISION_TOKENS_PER_FRAME,

package/src/utils/media_analysis_jobs.py

@@ -24,6 +24,7 @@ from src.utils.media_analysis import (
     detect_capabilities,
     execute_plan,
     normalize_path,
+    plan_requires_capabilities,
     resolve_output_root,
     stable_clip_directory,
     summarize_reports,
@@ -369,7 +370,7 @@ def create_batch_job(
     )
     if not plan.get("success"):
         return plan
-    if plan.get("capability_gaps"):
+    if plan.get("capability_gaps") and plan_requires_capabilities(plan):
         return {
             "success": False,
             "status": "missing_required_capabilities",