davinci-resolve-mcp 2.69.3 → 2.70.0

package/docs/reference/pixel-equality.md

@@ -0,0 +1,11 @@
+# Pixel equality: GUI vs headless rendered frames
+
+Frames are compared after decoding (ffmpeg `framemd5`), so container metadata cannot influence the result. `effective` is the within-mode control: whether the effect changed the picture at all relative to `plain`. An effect that is not effective makes its mode comparison meaningless, and is called out rather than counted as a pass.
+
+| effect | effective (GUI) | effective (headless) | pixels identical across modes |
+| --- | --- | --- | --- |
+| plain | — | — | **identical** |
+| transform | True | True | **identical** |
+| cdl | True | True | **identical** |
+| lut | True | True | **identical** |
+| fusion_comp | True | True | **identical** |

package/docs/reference/roundtrip-fidelity.md

@@ -0,0 +1,17 @@
+# Timeline round-trip fidelity: export, re-import, compare
+
+`exact` = every item's record start, duration and **source in-point** survived, with all media linked. Anything else is unusable for an iterative edit loop.
+
+| format | link strategy | GUI | headless |
+| --- | --- | --- | --- |
+| drt | reuse_pool | exact | exact |
+| fcpxml_1_10 | reuse_pool | exact | exact |
+| fcpxml_1_10 | import_source | exact | exact |
+| fcp7xml | reuse_pool | exact | exact |
+| fcp7xml | import_source | exact | exact |
+| aaf | reuse_pool | exact | exact |
+| aaf | import_source | exact | exact |
+| otio | reuse_pool | exact-but-4-offline | exact-but-4-offline |
+| otio | import_source | exact | exact |
+| edl | reuse_pool | exact | exact |
+| edl | import_source | exact | exact |

package/docs/reference/roundtrip-rich-fidelity.md

@@ -0,0 +1,18 @@
+# Complex-cut round trip: what each format keeps
+
+Two video tracks, audio, a per-item transform, clip colours, flags, item and timeline markers. `kept` = identical to the reference; `n/a` = the API would not set that dimension, so no format can be blamed for losing it.
+
+| format | mode | cut | tracks | transform | colour | flags | markers | timeline_markers | linkage |
+|  --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| drt | gui | kept | kept | kept | kept | kept | kept | kept | kept |
+| drt | headless | kept | kept | kept | kept | kept | kept | kept | kept |
+| fcpxml_1_10 | gui | kept | lost:2v1a!=2v2a | kept | lost | kept | lost | lost | kept |
+| fcpxml_1_10 | headless | kept | lost:2v1a!=2v2a | kept | lost | kept | lost | lost | kept |
+| fcp7xml | gui | kept | kept | lost:FlipX | lost | kept | lost | lost | kept |
+| fcp7xml | headless | kept | kept | lost:FlipX | lost | kept | lost | lost | kept |
+| aaf | gui | kept | kept | lost:all | lost | kept | lost | kept | kept |
+| aaf | headless | kept | kept | lost:all | lost | kept | lost | kept | kept |
+| otio | gui | lost:source | kept | kept | lost | lost | kept | kept | offline:4 |
+| otio | headless | lost:source | kept | kept | lost | lost | kept | kept | offline:4 |
+| edl | gui | lost | lost:1v1a!=2v2a | lost:item-count | lost | lost | lost | lost | kept |
+| edl | headless | lost | lost:1v1a!=2v2a | lost:item-count | lost | lost | lost | lost | kept |

package/install.py

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

package/scripts/bisect_headless_hang.py

@@ -0,0 +1,125 @@
+"""Walk the stress harness's setup sequence one call at a time, on a cold headless Resolve.
+
+Two things are recorded around EVERY call: how long it took, and whether the
+current database is still attached afterwards. The hang and the null database
+have so far only been seen together, from two different clients, so neither is
+known to cause the other. Checking the database between every step is what turns
+that correlation into an ordering — if the database goes null one step *before*
+the hang, it is a cause; if it only goes null once something is already blocked,
+it is a symptom.
+
+Each step has its own alarm, so a hang is reported with the culprit named instead
+of parking the process forever.
+"""
+import json
+import signal
+import sys
+import time
+from pathlib import Path
+
+sys.path.append(
+    "/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting/Modules"
+)
+import DaVinciResolveScript as dvr  # noqa: E402
+
+
+class Hang(Exception):
+    pass
+
+
+def _alarm(*_):
+    raise Hang()
+
+
+signal.signal(signal.SIGALRM, _alarm)
+RESULTS = []
+
+
+def step(label, fn, secs=45, pm=None):
+    """Run one call, timed, with the database checked immediately afterwards."""
+    signal.alarm(secs)
+    started = time.monotonic()
+    outcome, value = "ok", None
+    try:
+        value = fn()
+    except Hang:
+        outcome = "HUNG"
+    except Exception as exc:
+        outcome, value = "error", f"{type(exc).__name__}: {exc}"
+    finally:
+        signal.alarm(0)
+    elapsed = round(time.monotonic() - started, 1)
+
+    db = "unchecked"
+    if pm is not None and outcome != "HUNG":
+        signal.alarm(20)
+        try:
+            db = pm.GetCurrentDatabase()
+        except Hang:
+            db = "HUNG-checking-db"
+        except Exception as exc:
+            db = f"error: {type(exc).__name__}"
+        finally:
+            signal.alarm(0)
+
+    record = {"step": label, "outcome": outcome, "seconds": elapsed,
+              "value": repr(value)[:120], "database_after": db}
+    RESULTS.append(record)
+    print(json.dumps(record), flush=True)
+    if outcome == "HUNG":
+        print(f"\n>>> CULPRIT: {label} hung after {secs}s", flush=True)
+        dump()
+        raise SystemExit(9)
+    return value
+
+
+def dump():
+    Path(sys.argv[1]).write_text(json.dumps(RESULTS, indent=2, default=str))
+
+
+def main():
+    resolve = None
+    for _ in range(420):
+        resolve = dvr.scriptapp("Resolve")
+        if resolve is not None:
+            break
+        time.sleep(1)
+    if resolve is None:
+        raise SystemExit("no Resolve")
+
+    pm = step("GetProjectManager", resolve.GetProjectManager, pm=None)
+    step("GetCurrentDatabase (baseline)", pm.GetCurrentDatabase, pm=pm)
+    step("GetProjectListInCurrentFolder", lambda: len(pm.GetProjectListInCurrentFolder() or []), pm=pm)
+    incumbent = step("GetCurrentProject().GetName()",
+                     lambda: (pm.GetCurrentProject().GetName() if pm.GetCurrentProject() else None), pm=pm)
+    # The first suspect: SaveProject on the never-saved default project. It is
+    # the first mutating call the harness makes, and it is documented to return
+    # False for exactly this project.
+    step("SaveProject (incumbent)", pm.SaveProject, pm=pm)
+
+    name = "COLD_HEADLESS_PROBE"
+    step("CreateProject", lambda: bool(pm.CreateProject(name)), pm=pm)
+    step("LoadProject", lambda: bool(pm.LoadProject(name)), pm=pm)
+    project = step("GetCurrentProject", pm.GetCurrentProject, pm=pm)
+    if project is None:
+        dump()
+        raise SystemExit("no project after LoadProject")
+
+    step("GetMediaStorage", resolve.GetMediaStorage, pm=pm)
+    step("project.GetMediaPool", project.GetMediaPool, pm=pm)
+    step("GetRenderFormats", lambda: len(project.GetRenderFormats() or {}), pm=pm)
+    step("CreateEmptyTimeline", lambda: bool(project.GetMediaPool().CreateEmptyTimeline("COLD_TL")), pm=pm)
+
+    # Teardown, itself instrumented — the harness's teardown is as likely a
+    # suspect as its setup, and it runs on every iteration boundary.
+    step("SaveProject (scratch)", pm.SaveProject, pm=pm)
+    step("CloseProject", lambda: bool(pm.CloseProject(pm.GetCurrentProject())), pm=pm)
+    if incumbent:
+        step("LoadProject (incumbent)", lambda: bool(pm.LoadProject(incumbent)), pm=pm)
+    step("DeleteProject", lambda: bool(pm.DeleteProject(name)), pm=pm)
+    dump()
+    print("\n>>> COMPLETED WITH NO HANG", flush=True)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/contact_sheet.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""Labelled contact sheets from a media_analysis frames directory.
+
+Solves a concrete cost problem in the host-chat vision loop. `media_analysis`
+extracts sampled frames at FULL source resolution — a 35-minute 4K clip yields
+80 frames at 2160x3840, ~280 KB each. Reading those one at a time to satisfy
+`commit_vision` costs roughly 1,100 tokens per frame; a four-clip shoot runs to
+250+ frames and several hundred thousand tokens.
+
+Tiling them into labelled grids drops that by an order of magnitude while
+keeping every frame visible. Each tile is burned with its frame index, source
+timestamp and the sampler's `selection_reason`, so per-frame findings can still
+be reported by index against the schema.
+
+Source-safe: reads only the analysis scratch directory and the sidecar
+`visual.json`; writes only into `out_dir`. Never touches source media.
+
+Run: `python3 scripts/contact_sheet.py <clip_analysis_dir> <out_dir>`
+where `<clip_analysis_dir>` is the directory holding `visual.json` and
+`frames/` (printed as `artifacts.clip_dir` by `media_analysis`).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from typing import Any, Dict, List, Tuple
+
+try:
+    from PIL import Image, ImageDraw, ImageFont
+except ImportError:  # pragma: no cover - guidance only, never auto-installs
+    raise SystemExit(
+        "Pillow is required: pip install Pillow "
+        "(source-safe; used only to tile analysis scratch frames)"
+    )
+
+LABEL_HEIGHT = 26
+FONT_CANDIDATES = (
+    "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
+    "/System/Library/Fonts/Helvetica.ttc",
+    "/Library/Fonts/Arial.ttf",
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+)
+
+
+def _load_font(size: int):
+    for path in FONT_CANDIDATES:
+        if os.path.exists(path):
+            try:
+                return ImageFont.truetype(path, size)
+            except OSError:
+                continue
+    return ImageFont.load_default()
+
+
+def _timestamp(seconds: Any) -> str:
+    if seconds is None:
+        return "?"
+    minutes, secs = divmod(float(seconds), 60)
+    return "%d:%05.2f" % (int(minutes), secs)
+
+
+def _read_json(path: str) -> Dict[str, Any]:
+    try:
+        with open(path, encoding="utf-8") as handle:
+            return json.load(handle)
+    except (OSError, ValueError):
+        return {}
+
+
+def load_frames(clip_dir: str) -> Tuple[List[str], Dict[int, Dict[str, Any]]]:
+    """Resolve frame paths + per-frame labels across all three artifact states.
+
+    Order matters. While vision is pending, visual.json's `frame_paths` IS the
+    payload `commit_vision` expects findings reported against, so its indices
+    must win — analysis.json holds a larger superset (vision sample plus
+    cut-boundary frames) whose numbering would not line up.
+
+    `commit_vision` then REPLACES visual.json with the committed analysis,
+    dropping `frame_paths`. After that analysis.json's `analysis_keyframes` is
+    the richest surviving source, and index alignment no longer matters because
+    there is no vision payload left to report against.
+    """
+    visual = _read_json(os.path.join(clip_dir, "visual.json"))
+    paths = [p for p in visual.get("frame_paths", []) if os.path.exists(p)]
+    if paths:
+        meta = {
+            m["frame_index"]: m for m in visual.get("frame_metadata", [])
+        }
+        return paths, meta
+
+    keyframes = _read_json(os.path.join(clip_dir, "analysis.json")).get(
+        "analysis_keyframes"
+    )
+    if keyframes:
+        paths, meta = [], {}
+        for position, entry in enumerate(keyframes, start=1):
+            frame_path = entry.get("frame_path")
+            if not frame_path or not os.path.exists(frame_path):
+                continue
+            paths.append(frame_path)
+            meta[len(paths)] = {
+                "time_seconds": entry.get("time_seconds"),
+                "selection_reason": entry.get("selection_reason"),
+                "frame_index": entry.get("index", position),
+            }
+        if paths:
+            return paths, meta
+
+    frames_dir = os.path.join(clip_dir, "frames")
+    if os.path.isdir(frames_dir):
+        listed = sorted(
+            os.path.join(frames_dir, n)
+            for n in os.listdir(frames_dir)
+            if n.lower().endswith((".jpg", ".jpeg", ".png"))
+        )
+        return listed, {}
+
+    return [], {}
+
+
+def build_sheets(
+    clip_dir: str,
+    out_dir: str,
+    tile_width: int = 300,
+    columns: int = 6,
+    rows: int = 3,
+) -> Tuple[List[Tuple[str, int, int]], int]:
+    """Tile every sampled frame into labelled sheets. Returns (sheets, frame_count)."""
+    paths, meta = load_frames(clip_dir)
+    if not paths:
+        return [], 0
+
+    per_sheet = columns * rows
+    os.makedirs(out_dir, exist_ok=True)
+    font = _load_font(17)
+
+    # Derive tile height from a real frame — never assume 16:9. Vertical phone
+    # footage arrives here already rotated to portrait by ffmpeg.
+    with Image.open(paths[0]) as probe:
+        tile_height = max(1, round(tile_width * probe.height / probe.width))
+
+    sheets: List[Tuple[str, int, int]] = []
+    for offset in range(0, len(paths), per_sheet):
+        chunk = paths[offset:offset + per_sheet]
+        used_rows = (len(chunk) + columns - 1) // columns
+        sheet = Image.new(
+            "RGB",
+            (columns * tile_width, used_rows * (tile_height + LABEL_HEIGHT)),
+            (18, 18, 18),
+        )
+        draw = ImageDraw.Draw(sheet)
+
+        for position, frame_path in enumerate(chunk):
+            index = offset + position + 1
+            row, column = divmod(position, columns)
+            x = column * tile_width
+            y = row * (tile_height + LABEL_HEIGHT)
+            with Image.open(frame_path) as frame:
+                frame = frame.convert("RGB").resize(
+                    (tile_width, tile_height), Image.LANCZOS
+                )
+                sheet.paste(frame, (x, y + LABEL_HEIGHT))
+            entry = meta.get(index, {})
+            reason = (entry.get("selection_reason") or "")[:14]
+            draw.text(
+                (x + 5, y + 4),
+                "#%d  %s  %s" % (index, _timestamp(entry.get("time_seconds")), reason),
+                fill=(255, 220, 90),
+                font=font,
+            )
+
+        out_path = os.path.join(out_dir, "sheet_%02d.jpg" % (offset // per_sheet + 1))
+        sheet.save(out_path, quality=82, optimize=True)
+        sheets.append((out_path, offset + 1, offset + len(chunk)))
+
+    return sheets, len(paths)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("clip_dir", help="directory containing visual.json and frames/")
+    parser.add_argument("out_dir", help="where to write the contact sheets")
+    parser.add_argument("--tile-width", type=int, default=300)
+    parser.add_argument("--columns", type=int, default=6)
+    parser.add_argument("--rows", type=int, default=3)
+    args = parser.parse_args()
+
+    sheets, frame_count = build_sheets(
+        args.clip_dir, args.out_dir, args.tile_width, args.columns, args.rows
+    )
+    if not frame_count:
+        print(
+            "no sampled frames found in %s\n"
+            "expected analysis.json, visual.json, or a frames/ directory "
+            "(use the clip_dir printed as artifacts.clip_dir by media_analysis)"
+            % args.clip_dir
+        )
+        return 1
+
+    print("frames=%d sheets=%d" % (frame_count, len(sheets)))
+    for path, first, last in sheets:
+        print("%s  frames %d-%d" % (path, first, last))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())