davinci-resolve-mcp 2.132.1 → 2.133.0

package/docs/guides/headless-edit-loop.md

@@ -14,6 +14,18 @@ the raw runs are in `docs/reference/evidence/`.
 `-nogui` — the flat round trip, the complex-cut round trip, and the moved-media
 relink. Choose a format on its properties, never on whether you have a UI.
 
+**Precondition first, though: headless requires external scripting to connect
+without the GUI.** That held everywhere it was measured here, but at least one
+field setup (Studio 21.0.4.5, scripting routed through an external bridge
+process — issue #172) boots `-nogui` into an instance that *never answers*
+`scriptapp('Resolve')`, and an unscriptable headless instance still holds the
+one-per-machine singleton, so the GUI cannot start either. Preflight in 30
+seconds before committing a loop to `-nogui`:
+`python scripts/resolve_headless.py run -- python -c "print('ok')"` — a clean
+`ok` proves boot-to-scriptable; a `FAILED: no scripting response` now cleans up
+the instance it started, and `stop --force` TERM/KILLs a wedged one (unclean:
+expect project locks and a slow next boot).
+
 **There is no single best format.** Three measurements pull in different
 directions, and the right choice depends on which one you are up against:
 

package/install.py

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

package/resolve-advanced/server/author-interchange.mjs

@@ -608,13 +608,23 @@ export function verifyRoundtrip(inputEvents, exportedEvents, opts = {}) {
     return m ? `${m[1]}${m[2] || '1'}` : String(t);
   };
   const canonSource = (x) => String(x || '').replace(/\.[^.]+$/, '').toLowerCase();
-  const vids = (evts) => evts.filter((e) => /^V\d*$/.test(String(e.track)) && e.recIn != null && e.recOut != null);
+  // Reel/tape aliases: an EDL names sources by REEL (CUTSRC) while the
+  // re-export names them by file basename (cut_src) — the sourceMap that
+  // drove the assemble is the authority linking the two. Keys and values
+  // canonicalize exactly like event sources.
+  const aliases = {};
+  for (const [k, v] of Object.entries(opts.sourceAliases || {})) aliases[canonSource(k)] = canonSource(v);
+  const mapSource = (s) => aliases[s] ?? s;
+  // recOut > recIn: an EDL dissolve writes a ZERO-duration outgoing leg
+  // before the D event — a pairing placeholder, never a rendered clip, and
+  // no export reproduces it.
+  const vids = (evts) => evts.filter((e) => /^V\d*$/.test(String(e.track)) && e.recIn != null && e.recOut != null && e.recOut > e.recIn);
   const norm = (evts) => {
     const v = vids(evts);
     if (!v.length) return [];
     const off = Math.min(...v.map((e) => e.recIn));
     return v
-      .map((e) => ({ track: canonTrack(e.track), source: canonSource(e.source), recIn: e.recIn - off, recOut: e.recOut - off, srcIn: e.srcIn ?? 0 }))
+      .map((e) => ({ track: canonTrack(e.track), source: mapSource(canonSource(e.source)), recIn: e.recIn - off, recOut: e.recOut - off, srcIn: e.srcIn ?? 0 }))
       .sort((a, b) => a.track.localeCompare(b.track) || a.recIn - b.recIn);
   };
   const a = norm(inputEvents);

package/resolve-advanced/server/tools/drt.mjs

@@ -288,8 +288,7 @@ export const drtTool = {
         stamped,
         conform: report,
         note:
-          'Import with timeline.import_timeline_checked (timeline is named after the FILE). Dissolves/cross-fades, forward+reverse retimes, multi-track video, audio events and markers are AUTHORED when geometry allows; everything else drops WITH a reason — see `conform` for the ledger.' +
-          'Retimes are flattened and transitions become cuts — see `conform` for the ledger.',
+          'Import with timeline.import_timeline_checked (timeline is named after the FILE). Dissolves/cross-fades, forward+reverse retimes, multi-track video, audio events and markers are AUTHORED when geometry allows; everything else drops WITH a reason — see `conform` for the ledger.',
       };
     }
     if (action === 'assemble') {

package/resolve-advanced/server/tools/editorial.mjs

@@ -156,8 +156,17 @@ export const editorialTool = {
         exported: z.array(z.any()).describe('Normalized events of the re-export (parse_interchange on the exported OTIO/EDL/XML)'),
         recTol: z.number().optional(),
         srcTol: z.number().optional(),
+        sourceMap: z.record(z.object({ mediaFilePath: z.string() }).passthrough()).optional()
+          .describe('The SAME reel→{mediaFilePath} map the assemble used — lets an EDL reel (CUTSRC) match the re-export\'s file basename (cut_src)'),
       }).parse(args);
-      return verifyRoundtrip(p.input, p.exported, { recTol: p.recTol, srcTol: p.srcTol });
+      // EDL reels vs exported basenames: derive the alias table from the
+      // sourceMap that drove the assemble (the one authority linking them).
+      const sourceAliases = {};
+      for (const [reel, src] of Object.entries(p.sourceMap || {})) {
+        const base = String(src.mediaFilePath).split('/').pop();
+        if (base) sourceAliases[reel] = base;
+      }
+      return verifyRoundtrip(p.input, p.exported, { recTol: p.recTol, srcTol: p.srcTol, sourceAliases });
     }
     if (action === 'marker_roundtrip') {
       const p = markerSchema.parse(args);

package/resolve-advanced/vendor/drp-format/assemble-timeline.js

@@ -200,6 +200,17 @@ async function assembleTimeline(spec = {}) {
     }));
   }
 
+  // Pin the PARENT container id BEFORE any compound inserts an inner
+  // container: entry listing is name-sorted, so an inner container can
+  // alphabetically precede the parent and every later "first container"
+  // lookup — the next compound's item, subtitles, markers — then targets
+  // the compound's INNER timeline instead (measured: CMP_B landed inside
+  // CMP_A; subtitles authored with a compound in the spec vanished into
+  // the inner container and the imported timeline had no subtitle track).
+  const zipPin = await JSZip.loadAsync(buffer);
+  const parentEntryPin = Object.keys(zipPin.files).find((n) => !zipPin.files[n].dir && /SeqContainer\/.+\.xml$/.test(n));
+  const parentContainerId = ((await zipPin.file(parentEntryPin).async('string')).match(/<Sm2SequenceContainer DbId="([^"]+)"/) || [])[1];
+
   // Compound clips: an empty nested timeline is spliced in from the
   // harvested donor shape, then its content is placed with the ORDINARY cuts
   // machinery targeting the inner container (inner origin is FRAME 0).
@@ -221,13 +232,6 @@ async function assembleTimeline(spec = {}) {
         insertedExtra.add(fp);
       }
     }
-    // Pin the PARENT container id BEFORE inserting inner containers: entry
-    // listing is name-sorted, so an inner container can alphabetically
-    // precede the parent and swallow the next compound's item (measured —
-    // CMP_B landed inside CMP_A's inner timeline).
-    const zip0 = await JSZip.loadAsync(buffer);
-    const parentEntry0 = Object.keys(zip0.files).find((n) => !zip0.files[n].dir && /SeqContainer\/.+\.xml$/.test(n));
-    const parentContainerId = ((await zip0.file(parentEntry0).async('string')).match(/<Sm2SequenceContainer DbId="([^"]+)"/) || [])[1];
     for (const [ci, comp] of spec.compounds.entries()) {
       if (!comp || typeof comp !== 'object') throw new TypeError(`assembleTimeline: compounds[${ci}] must be an object`);
       const res = await placeCompound(buffer, {
@@ -280,7 +284,7 @@ async function assembleTimeline(spec = {}) {
         throw new RangeError(`assembleTimeline: subtitle at frame ${sub.startFrame} is before the timeline origin ${originFrame}`);
       }
     }
-    ({ buffer } = await placeSubtitles(buffer, { subtitles }));
+    ({ buffer } = await placeSubtitles(buffer, { subtitles, timelineUuid: parentContainerId }));
   }
 
   if (Array.isArray(spec.markers) && spec.markers.length) {
@@ -289,9 +293,17 @@ async function assembleTimeline(spec = {}) {
     // <Sequence> references). Encoder byte-exact vs a live 19.1.3.7 export.
     // Marker frames here are TIMELINE-ABSOLUTE for consistency with cuts;
     // the blob stores them start-relative.
+    // Resolved against the PINNED parent container — a compound's inner
+    // container also matches the "any SeqContainer entry" pattern, and
+    // attaching the blob to the inner sequence hides every marker.
     const zipM = await JSZip.loadAsync(buffer);
-    const seqName = Object.keys(zipM.files).find((n) => !zipM.files[n].dir && /SeqContainer\/.+\.xml$/.test(n));
-    const seqXml2 = await zipM.file(seqName).async('string');
+    const seqNames = Object.keys(zipM.files).filter((n) => !zipM.files[n].dir && /SeqContainer\/.+\.xml$/.test(n));
+    let seqXml2 = null;
+    for (const n of seqNames) {
+      const xmlN = await zipM.file(n).async('string');
+      if (xmlN.includes(`<Sm2SequenceContainer DbId="${parentContainerId}"`)) { seqXml2 = xmlN; break; }
+    }
+    if (!seqXml2) throw new Error('assembleTimeline: pinned parent SeqContainer not found for markers');
     const seqIdM = (seqXml2.match(/<Sequence>([0-9a-f-]{36})<\/Sequence>/) || [])[1];
     if (!seqIdM) throw new Error('assembleTimeline: cannot find the Sm2Sequence id for markers');
     const rel = spec.markers.map((m) => {

package/scripts/resolve_headless.py

@@ -5,6 +5,7 @@
     python scripts/resolve_headless.py guard      # exit non-zero unless it is safe to start
     python scripts/resolve_headless.py start      # boot -nogui and wait until scriptable
     python scripts/resolve_headless.py stop       # Quit() and wait for the process to go
+    python scripts/resolve_headless.py stop --force  # TERM/KILL a wedged, unanswering instance
     python scripts/resolve_headless.py run -- python my_batch.py   # guard, start, run, stop
 
 Why a wrapper rather than a line in a Makefile:
@@ -122,6 +123,21 @@ def cmd_guard() -> int:
     return 0
 
 
+def _kill_process(proc: subprocess.Popen, grace: float = 10.0) -> bool:
+    """TERM then KILL the process we launched; True when it is gone."""
+    proc.terminate()
+    try:
+        proc.wait(timeout=grace)
+        return True
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        try:
+            proc.wait(timeout=grace)
+            return True
+        except subprocess.TimeoutExpired:
+            return False
+
+
 def start(timeout: float) -> int:
     guard = cmd_guard()
     if guard != 0:
@@ -131,25 +147,41 @@ def start(timeout: float) -> int:
         print("REFUSE: no DaVinci Resolve install found.", file=sys.stderr)
         return 3
     print(f"starting: {' '.join(command)}")
-    subprocess.Popen(command, stdin=subprocess.DEVNULL,
-                     stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    proc = subprocess.Popen(command, stdin=subprocess.DEVNULL,
+                            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
     started = time.monotonic()
     if wait_until_scriptable(timeout) is None:
+        # An unscriptable -nogui instance still holds the singleton, so the
+        # GUI cannot launch either — leaving it behind wedges the machine
+        # worse than never starting (issue #172). Kill only what WE spawned.
         print(f"FAILED: no scripting response within {timeout:.0f}s.", file=sys.stderr)
+        print("cleaning up the unscriptable instance this script started...", file=sys.stderr)
+        if _kill_process(proc):
+            print("cleaned up. Headless requires external scripting to connect without "
+                  "the GUI; on this setup it did not — use the GUI, or raise --timeout "
+                  "if this machine is just slow to boot Resolve.", file=sys.stderr)
+        else:
+            print(f"could not kill pid {proc.pid} — remove it by hand (kill -9 {proc.pid}).",
+                  file=sys.stderr)
         return 4
     print(f"ready in {time.monotonic() - started:.1f}s")
     return 0
 
 
-def stop(timeout: float) -> int:
+def stop(timeout: float, force: bool = False) -> int:
     mode = rr.runtime_mode()
     if not mode["running"]:
         print("nothing to stop")
         return 0
     resolve = _connect()
     if resolve is None:
-        print("REFUSE: Resolve is running but not answering; not killing it.", file=sys.stderr)
-        return 5
+        if not force:
+            print("REFUSE: Resolve is running but not answering; not killing it. "
+                  "If it never became scriptable (a wedged -nogui boot, a stuck "
+                  "modal), rerun with --force to TERM/KILL it — unclean: expect "
+                  "project locks and a slow next boot.", file=sys.stderr)
+            return 5
+        return _force_stop(timeout)
     started = time.monotonic()
     resolve.Quit()
     while time.monotonic() - started < timeout:
@@ -157,10 +189,55 @@ def stop(timeout: float) -> int:
         if not (rr.resolve_processes() or []):
             print(f"stopped in {time.monotonic() - started:.1f}s")
             return 0
-    print(f"FAILED: still running {timeout:.0f}s after Quit().", file=sys.stderr)
+    if force:
+        print(f"still running {timeout:.0f}s after Quit(); escalating.", file=sys.stderr)
+        return _force_stop(timeout)
+    print(f"FAILED: still running {timeout:.0f}s after Quit(). "
+          f"Rerun with --force to TERM/KILL it.", file=sys.stderr)
     return 6
 
 
+def _force_stop(timeout: float) -> int:
+    """TERM, then KILL, every running Resolve process (unix only)."""
+    import platform
+    import signal
+
+    if platform.system().lower() == "windows":
+        print("FAILED: --force is unix-only here; use `taskkill /F /IM Resolve.exe`.",
+              file=sys.stderr)
+        return 7
+
+    def pids() -> List[int]:
+        found: set = set()
+        for name in ("Resolve", "resolve"):
+            out = subprocess.run(["pgrep", "-x", name], capture_output=True,
+                                 text=True, check=False)
+            found.update(int(p) for p in out.stdout.split() if p.strip().isdigit())
+        return sorted(found)
+
+    for sig, grace in ((signal.SIGTERM, min(timeout, 10.0)), (signal.SIGKILL, min(timeout, 10.0))):
+        targets = pids()
+        if not targets:
+            print("force-stopped (unclean — expect a slower next boot).")
+            return 0
+        for pid in targets:
+            print(f"sending {sig.name} to pid {pid}", file=sys.stderr)
+            try:
+                os.kill(pid, sig)
+            except ProcessLookupError:
+                pass
+            except PermissionError:
+                print(f"no permission to signal pid {pid}", file=sys.stderr)
+        deadline = time.monotonic() + grace
+        while time.monotonic() < deadline:
+            time.sleep(0.5)
+            if not pids():
+                print("force-stopped (unclean — expect a slower next boot).")
+                return 0
+    print("FAILED: Resolve survived SIGKILL; inspect by hand.", file=sys.stderr)
+    return 7
+
+
 def cmd_run(command: List[str], timeout: float) -> int:
     """Guard, start if needed, run the command, stop only what we started."""
     mode = rr.runtime_mode()
@@ -200,7 +277,10 @@ def main() -> int:
     sub.add_parser("status")
     sub.add_parser("guard")
     sub.add_parser("start")
-    sub.add_parser("stop")
+    stop_p = sub.add_parser("stop")
+    stop_p.add_argument("--force", action="store_true",
+                        help="escalate to TERM/KILL when Resolve is running but not "
+                             "answering, or survives Quit() (unclean shutdown)")
     run = sub.add_parser("run")
     run.add_argument("argv", nargs=argparse.REMAINDER,
                      help="command to run; put it after a bare --")
@@ -213,7 +293,7 @@ def main() -> int:
     if args.command == "start":
         return start(args.timeout)
     if args.command == "stop":
-        return stop(args.timeout)
+        return stop(args.timeout, force=getattr(args, "force", False))
     argv = [a for a in args.argv if a != "--"]
     if not argv:
         print("run: nothing to run (put the command after `--`)", file=sys.stderr)

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.132.1"
+VERSION = "2.133.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 353-tool granular server instead
 """
 
-VERSION = "2.132.1"
+VERSION = "2.133.0"
 
 import base64
 import os