davinci-resolve-mcp 2.103.0 → 2.103.2

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 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.103.2
+
+**A Windows setup that failed with nothing to read.** Reported in issue #158 by
+@KMiNT21 on a machine carrying both Python 3.12 and 3.13: `npx davinci-resolve-mcp`
+exited without a traceback, a log line, or an error. Three defects compounded.
+
+The first is the one that mattered. The npm launcher tested for the Windows `py`
+launcher with `py --version`, and that result gated the entire `py -3.12 / -3.11 /
+-3.10` candidate list. `py` does not accept `--version` on every build — it exits
+101 on the ones it does not — so on those machines the probe reported no launcher,
+every version-pinned candidate was discarded, and selection fell through to bare
+`python`: the 3.13 that the candidate ordering exists specifically to avoid. The
+3.13 protections added in v2.26.1 were not wrong; they were being skipped past.
+
+The fix removes the probe rather than correcting its flag. `checkPython()` already
+validates each candidate by running it, so a machine without `py` costs one failed
+spawn. A probe that can produce a false negative earns its place only if something
+downstream cannot do without it, and nothing here needed it.
+
+### Fixed
+
+- `bin/davinci-resolve-mcp.mjs` no longer gates the `py -3.x` candidates behind a
+  `py --version` probe.
+- An access-violation exit is now explained instead of propagated bare. Windows
+  reports `STATUS_ACCESS_VIOLATION` as an exit code (`3221225477`, or `-1073741819`
+  read signed), not as a signal — the interpreter dies inside the native library
+  with no chance to print. Both the launcher and `install.py`'s connection probe now
+  name the code, say why there is no traceback, and give the remedy. Previously the
+  probe could only report `Process exited with code 3221225477`.
+- `scripts/doctor.py` consults the runtime discovery helpers when every candidate
+  path misses, so Resolve installed off the conventional root (the reporter had it
+  on `D:`) is found rather than reported as four FAILs on a machine `install.py` had
+  just configured correctly. Same shape as issue #106.
+- `scripts/doctor.py` no longer reports a client config as `missing` because of path
+  escaping. A Windows path written into JSON comes back with doubled separators, and
+  the literal substring test could never match it — a false negative in the tool
+  whose job is to say whether setup worked.
+
+### Not changed
+
+Python 3.13 is still permitted. The policy set in v2.26.1 is a 3.10 floor with no
+cap — warn, do not block — and issue #158 proposed enforcing 3.10-3.12 on Windows.
+The candidate ordering already prefers the lower-risk interpreters; the bug was that
+ordering being bypassed, which is now fixed.
+
+### Coverage and its limits
+
+`tests/test_windows_python_crash.py` pins the launcher's candidate shape and the
+crash-code translation; `tests/test_doctor_paths.py` gains the discovery and
+path-escaping cases. All were confirmed to fail against the unfixed code.
+
+What is **not** covered, and is not coverable from macOS: whether `py --version`
+actually fails on any given Windows build. That claim comes from the reporter. The
+fix does not rest on it — it removes the probe rather than correcting it, so the
+code no longer has an opinion either way. The access-violation paths are likewise
+tested by injecting the exit code, not by producing a real crash.
+
+## What's New in v2.103.1
+
+**A loudness measurement could silently become a single frame's reading.**
+`media_analysis`'s EBU R128 parser took the last match for `I:`, `LRA:` and `Peak:`
+across the whole of ffmpeg's stderr. `ebur128` prints a progress line per frame carrying
+those same fields, so that read was correct only because the `Summary:` block happens to
+print last. Nothing enforces that ordering, and when it does not hold the numbers still
+parse — a delivery-grade figure is quietly replaced by one frame's, with no error to
+notice.
+
+### Fixed
+
+- `media_analysis._parse_loudness` now reads the summary block and nothing else.
+- Both callers share one parser, `src/utils/loudness_parse.py`. The regexes were
+  duplicated so `mix_plan` stayed importable without the analysis engine; that argument
+  covers the engine, not the parsing rule, and a rule that has to be right in two places
+  is one that eventually is not.
+- Absent a summary the result is `None`, not a best guess. "No measurement" and
+  "one frame's measurement" are different answers, and only one is safe to deliver on.
+
+### How the block is bounded
+
+Two independent guards, because each rests on a different assumption about ffmpeg's
+output and either can outlive the other:
+
+1. **Block bounding** — seek the last `Summary:`, then take lines until the next ffmpeg
+   log line. The summary body is indented plain text while every log line carries a
+   `[component @ address]` prefix, so the block ends at `[out#0/null …]`, at a trailing
+   progress line, and at anything else appended after it.
+2. **`TARGET:` filtering** — the field on every progress line and on nothing in the
+   summary. This is what still holds if a progress line ever arrives without the
+   bracketed prefix, and it is what makes the no-summary path return `None`.
+
+### Validation
+
+- Offline suite: 2980 passed, 1 skipped, 725 subtests, 0 failures (was 2959/719).
+- Verified against real ffmpeg output, not only fixtures: a live `ebur128` run is parsed
+  and the block asserted to end before ffmpeg's own trailer.
+- Four deliberate mutations — no scoping, locating the summary without bounding the
+  block, bounding it without the `TARGET:` filter, and falling back to the raw stream
+  when no summary printed — were each caught. The third initially survived, and the test
+  isolating that guard was added until it failed.
+- No Resolve behavior changed; live test not required.
+
 ## What's New in v2.103.0
 
 **An unreachable Resolve no longer ends the work.** The interchange authoring that can

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.103.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.103.2-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-36%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.103.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.103.2-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-36%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.103.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.103.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/bin/davinci-resolve-mcp.mjs

@@ -179,14 +179,6 @@ function syncManagedInstall(root) {
   return root;
 }
 
-function commandExists(command, args = []) {
-  const result = spawnSync(command, [...args, "--version"], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  return result.status === 0;
-}
-
 function parseExecutable(value) {
   if (!value) {
     return null;
@@ -207,7 +199,14 @@ function pythonCandidates() {
   // Prefer the lowest-ABI-risk interpreters first, then newer ones, then the
   // generic launchers. All 3.10+ are accepted; ordering just picks the safest
   // when several are installed.
-  if (process.platform === "win32" && commandExists("py")) {
+  // No existence probe in front of these. `py --version` is not a reliable
+  // one — the Windows launcher does not accept it on every build, and it
+  // exits 101 on the ones it does not (issue #158). A probe that gets that
+  // wrong discards every version-pinned candidate below and falls through to
+  // bare `python`, which is exactly the 3.13 the ordering exists to avoid.
+  // checkPython() runs each candidate anyway, so a missing `py` costs one
+  // failed spawn and is skipped.
+  if (process.platform === "win32") {
     candidates.push(
       { command: "py", args: ["-3.12"] },
       { command: "py", args: ["-3.11"] },
@@ -317,6 +316,24 @@ function venvPython(root) {
   return info;
 }
 
+// Windows reports a hard access violation as the process exit code, not as a
+// signal and not as a traceback: the interpreter is gone before it can say
+// anything. Loading Resolve's fusionscript under a Python its C ABI does not
+// match is one way to get there, so name that possibility rather than letting
+// the run end in a bare unexplained code (issue #158).
+const WINDOWS_ACCESS_VIOLATION = [3221225477, -1073741819];
+
+function accessViolationNote(code) {
+  return [
+    `The Python process was terminated by an access violation (0x${(code >>> 0).toString(16).toUpperCase()}).`,
+    "It crashed inside a native library before it could report anything, so there is no traceback above.",
+    "The usual cause is Resolve's scripting library being loaded by a Python whose C ABI it was not built",
+    "against. If you are on Python 3.13+, install Python 3.10-3.12 and pin it:",
+    "  DAVINCI_RESOLVE_MCP_PYTHON=C:\\Path\\To\\python3.12.exe",
+    "then re-run setup so the managed venv is rebuilt on that interpreter.",
+  ].join("\n");
+}
+
 function run(command, args, options = {}) {
   const child = spawn(command, args, {
     cwd: options.cwd,
@@ -329,6 +346,9 @@ function run(command, args, options = {}) {
       process.kill(process.pid, signal);
       return;
     }
+    if (WINDOWS_ACCESS_VIOLATION.includes(code)) {
+      console.error(accessViolationNote(code));
+    }
     process.exit(code ?? 1);
   });
   child.on("error", (error) => {

package/docs/install.md

@@ -86,6 +86,7 @@ The installer can automatically configure any of these clients:
 
 | Client | Config Written To |
 |--------|-------------------|
+| Antigravity (Google) | `~/.gemini/antigravity/mcp_config.json` (all platforms) |
 | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS); `%APPDATA%\Claude\claude_desktop_config.json` (Windows, see MSIX note below) |
 | Claude Code | `.mcp.json` (project root) |
 | Cursor | `~/.cursor/mcp.json` |

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.103.0"
+VERSION = "2.103.2"
 # 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
@@ -1253,6 +1253,54 @@ def install_dependencies(venv_path, project_dir):
 
 # ─── Connection Verification ─────────────────────────────────────────────────
 
+#: Windows surfaces a hard access violation (STATUS_ACCESS_VIOLATION) as a
+#: process exit code. Both spellings appear in the wild: the unsigned value and
+#: the signed reading of the same 32 bits. The interpreter dies inside the
+#: native library, so there is no traceback and no stderr to report — without
+#: this translation the probe can only say "exited with code 3221225477",
+#: which is the shape issue #158 was reported as.
+WINDOWS_ACCESS_VIOLATION_CODES = (3221225477, -1073741819)
+
+
+def _version_parts(version):
+    """A `(major, minor, ...)` int tuple, or None if it cannot be read.
+
+    `is_abi_risk_python_version` unpacks `version[:2]`, so handing it the string
+    "3.13.3" yields `("3", ".")` and a quiet False — the interpreter most likely
+    to have caused the crash would be reported as not at risk. Normalizing here
+    means a caller cannot make that mistake by passing the obvious thing.
+    """
+    if version is None:
+        return None
+    if isinstance(version, str):
+        try:
+            return tuple(int(part) for part in version.split(".")[:3])
+        except ValueError:
+            return None
+    try:
+        return tuple(int(part) for part in tuple(version)[:3])
+    except (TypeError, ValueError):
+        return None
+
+
+def access_violation_message(returncode, version=None):
+    """Explain an access-violation exit, naming the ABI theory when it fits."""
+    text = (
+        "Python crashed with an access violation (0xC0000005) while loading "
+        "Resolve's scripting library — no traceback is possible, the process "
+        "was terminated by the OS."
+    )
+    parts = _version_parts(version)
+    if parts is None or is_abi_risk_python_version(parts):
+        text += (
+            " This is the signature of a C ABI mismatch: recreate the venv on "
+            "Python 3.10-3.12 (e.g. DAVINCI_RESOLVE_MCP_PYTHON=...\\python3.12.exe)."
+        )
+    else:
+        text += " Check that RESOLVE_SCRIPT_LIB names the library from your Resolve install."
+    return text
+
+
 def verify_resolve_connection(python_path, api_path, lib_path):
     """Try to import DaVinciResolveScript and connect."""
     if not api_path:
@@ -1311,6 +1359,12 @@ def verify_resolve_connection(python_path, api_path, lib_path):
         elif output.startswith("IMPORTED_OK:"):
             return True, "API module loaded (Resolve not running)"
         else:
+            if result.returncode in WINDOWS_ACCESS_VIOLATION_CODES:
+                try:
+                    version = _version_for_python(python_path)
+                except Exception:
+                    version = None
+                return False, access_violation_message(result.returncode, version)
             if output:
                 return False, output
             return False, f"Process exited with code {result.returncode}"
@@ -2219,7 +2273,10 @@ def main():
                     "             Point RESOLVE_SCRIPT_LIB at the fusionscript library inside your "
                     "Resolve install, or start Resolve and re-run setup."
                 )
-            if py_abi_risk:
+            if py_abi_risk and "0xC0000005" not in message:
+                # The access-violation message already carries this remedy, and
+                # states it as a diagnosis rather than a maybe. Do not follow it
+                # with a weaker restatement of itself.
                 print(
                     f"             On Python 3.13+ this may be an ABI mismatch with Resolve's "
                     f"scripting library — try Python 3.10-3.12 if it persists."

package/package.json

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

package/scripts/doctor.py

@@ -95,13 +95,64 @@ def _platform_key(platform: str | None = None) -> str:
     return "linux"
 
 
+def _discovered_default(kind: str) -> str | None:
+    """Ask the runtime helpers where Resolve actually is.
+
+    The candidate table above is a table of *conventional* locations. Resolve is
+    routinely installed somewhere else — a second drive is the common case,
+    because the application and its caches are large (issue #158 reported
+    `D:\\Programs\\DaVinci Resolve`). install.py already looks past the table
+    via these helpers; doctor did not, so it reported FAIL on installs the
+    installer had just configured correctly. That disagreement between two tools
+    describing one machine is the same failure shape as issue #106.
+
+    Only consulted when no candidate exists, and only for the two kinds the
+    helpers can answer. `api` has no discovery helper, so a non-default install
+    can still miss there — worth knowing when reading a report.
+    """
+    if str(REPO) not in sys.path:
+        # doctor is run standalone (`python scripts/doctor.py`) as often as it is
+        # run through the launcher, and only the latter puts the repo on the path.
+        sys.path.insert(0, str(REPO))
+
+    if kind == "lib":
+        try:
+            from src.utils.platform import discover_scripting_lib
+        except Exception:
+            return None
+        try:
+            discovered = discover_scripting_lib()
+        except Exception:
+            return None
+        return str(discovered) if discovered and Path(discovered).exists() else None
+
+    if kind == "app":
+        try:
+            from src.utils.resolve_runtime import _executable_from_line, resolve_processes
+        except Exception:
+            return None
+        try:
+            processes = resolve_processes() or []
+        except Exception:
+            return None
+        for line in processes:
+            executable = _executable_from_line(line)
+            if executable and Path(executable).exists():
+                return str(executable)
+    return None
+
+
 def _resolve_default(kind: str, platform: str | None = None) -> str:
-    """First candidate of `kind` that exists, else the first (so the FAIL line
-    names the canonical location rather than an arbitrary miss)."""
+    """First candidate of `kind` that exists, then discovery, else the first
+    candidate (so the FAIL line names the canonical location rather than an
+    arbitrary miss)."""
     candidates = _RESOLVE_PATH_CANDIDATES[_platform_key(platform)][kind]
     for candidate in candidates:
         if Path(candidate).exists():
             return candidate
+    discovered = _discovered_default(kind)
+    if discovered:
+        return discovered
     return candidates[0]
 
 
@@ -170,11 +221,27 @@ def check(results: list[dict[str, str]], status: str, name: str, detail: str) ->
     results.append({"status": status, "name": name, "detail": detail})
 
 
+def _normalize_separators(text: str) -> str:
+    r"""Collapse every run of backslashes to a single forward slash.
+
+    A Windows path does not survive a literal substring test against the file it
+    was written into: JSON escapes `C:\Users\x` as `C:\\Users\\x`, and TOML
+    may keep it single-escaped or write a literal string. doctor compared the
+    unescaped path against the raw file text and so reported the entry missing
+    on configs it had itself just written (issue #158).
+
+    Collapsing runs — rather than only the doubled form — is what makes both
+    spellings compare equal, and normalizing the needle the same way keeps the
+    comparison symmetric.
+    """
+    return re.sub(r"\\+", "/", text)
+
+
 def file_contains(path: Path, needles: list[str]) -> tuple[bool, str]:
     if not path.exists():
         return False, "missing"
-    text = path.read_text(errors="replace")
-    missing = [needle for needle in needles if needle not in text]
+    text = _normalize_separators(path.read_text(errors="replace"))
+    missing = [needle for needle in needles if _normalize_separators(needle) not in text]
     if missing:
         return False, "missing: " + ", ".join(missing)
     return True, "contains davinci-resolve MCP entry"

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.103.0"
+VERSION = "2.103.2"
 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.103.0"
+VERSION = "2.103.2"
 
 import base64
 import os

package/src/utils/loudness_parse.py

@@ -0,0 +1,90 @@
+"""Read EBU R128 figures out of ffmpeg's `ebur128` output, and nothing else out of it.
+
+One parser, imported by both callers. There were two: `media_analysis` measures loudness
+during analysis and `mix_plan` measures the premix it just rendered, and they carried
+copies of the same three regexes on the reasoning that `mix_plan` should stay importable
+without pulling in the analysis engine. That reasoning still holds for the *engine*; it
+does not justify two copies of the parsing rule, which is the part that has to be right.
+
+## The rule
+
+`ebur128` prints a progress line per frame carrying its own `I:`, `LRA:` and peak fields,
+then a `Summary:` block at the end. A last-match-wins read over the whole stream picks
+the summary only because the summary happens to print last. Nothing enforces that, and
+when it does not hold the numbers still parse — they are simply a single frame's reading
+presented as a programme measurement. There is no error to notice.
+
+So the summary block is *bounded*, not merely located:
+
+1. Seek the last `Summary:`.
+2. Take lines until the next ffmpeg log line — the block's body is indented plain text,
+   while every log line carries a `[component @ address]` prefix. That ends the block at
+   `[out#0/null …]`, at a trailing progress line, and at anything else ffmpeg appends.
+3. Drop any remaining `TARGET:` line, which is the field on every progress line and on
+   nothing in the summary. This is what protects the fallback path when no summary was
+   printed at all: there, reading a progress line would be the worst possible answer, so
+   the result is `None`.
+
+Absent a summary the answer is `None` rather than a best guess. "No measurement" and
+"a measurement of one frame" are different, and only one of them is safe to deliver on.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable, Dict, Optional
+
+INTEGRATED_RE = r"I:\s*(-?\d+(?:\.\d+)?)\s*LUFS"
+LRA_RE = r"LRA:\s*(-?\d+(?:\.\d+)?)\s*LU"
+PEAK_RE = r"Peak:\s*(-?\d+(?:\.\d+)?)\s*dBFS"
+
+#: ffmpeg prefixes every log line with `[component @ 0xaddr]`. The summary body does not
+#: carry one, so this is where the block ends.
+_LOG_LINE_PREFIX = "["
+
+
+def summary_block(stderr: str) -> str:
+    """The `ebur128` summary block alone, or "" when none was printed."""
+    marker = stderr.rfind("Summary:")
+    if marker < 0:
+        return ""
+    # Back up to the line start: `Summary:` sits at the end of an ffmpeg log line, and a
+    # block that begins mid-line would make the "first line is the header" rule below
+    # depend on where the word happened to fall.
+    line_start = stderr.rfind("\n", 0, marker) + 1
+    lines = stderr[line_start:].splitlines()
+    block = [lines[0]] if lines else []
+    for line in lines[1:]:
+        if line.startswith(_LOG_LINE_PREFIX):
+            break
+        block.append(line)
+    return "\n".join(line for line in block if "TARGET:" not in line)
+
+
+def parse_loudness(
+    stderr: str, *, to_float: Optional[Callable[[Any], Optional[float]]] = None
+) -> Dict[str, Optional[float]]:
+    """Integrated LUFS, loudness range, and true peak from the summary block.
+
+    `to_float` lets a caller supply its own lenient conversion; the default is `float`
+    with a `None` on failure.
+    """
+    convert = to_float or _default_float
+    scope = summary_block(stderr)
+
+    def latest(pattern: str) -> Optional[float]:
+        matches = re.findall(pattern, scope)
+        return convert(matches[-1]) if matches else None
+
+    return {
+        "integrated_lufs": latest(INTEGRATED_RE),
+        "loudness_range_lu": latest(LRA_RE),
+        "true_peak_dbtp": latest(PEAK_RE),
+    }
+
+
+def _default_float(value: Any) -> Optional[float]:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None

package/src/utils/media_analysis.py

@@ -2659,17 +2659,17 @@ def _ffmpeg_stderr_filter(path: str, video_filter: Optional[str] = None, audio_f
 
 
 def _parse_loudness(stderr: str) -> Dict[str, Any]:
-    def latest(pattern: str) -> Optional[float]:
-        matches = re.findall(pattern, stderr)
-        if not matches:
-            return None
-        return _parse_float(matches[-1])
+    """EBU R128 figures from ffmpeg's `ebur128` output.
 
-    return {
-        "integrated_lufs": latest(r"I:\s*(-?\d+(?:\.\d+)?)\s*LUFS"),
-        "loudness_range_lu": latest(r"LRA:\s*(-?\d+(?:\.\d+)?)\s*LU"),
-        "true_peak_dbtp": latest(r"Peak:\s*(-?\d+(?:\.\d+)?)\s*dBFS"),
-    }
+    Delegates to `loudness_parse`, which bounds the summary block rather than taking the
+    last match in the stream. `ebur128`'s per-frame progress lines carry their own `I:`,
+    `LRA:` and peak fields, so a last-match read is right only while the summary happens
+    to print last — and when it is not, the numbers still parse and a single frame is
+    reported as a programme measurement, with nothing to notice.
+    """
+    from src.utils import loudness_parse
+
+    return dict(loudness_parse.parse_loudness(stderr, to_float=_parse_float))
 
 
 def _parse_scene_changes(stderr: str) -> List[Dict[str, Any]]:

package/src/utils/mix_plan.py

@@ -56,7 +56,7 @@ import subprocess
 import tempfile
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 
-from . import delivery_targets
+from . import delivery_targets, loudness_parse
 
 try:
     import numpy as _np
@@ -107,39 +107,11 @@ def _require() -> None:
 
 # ── measurement ──────────────────────────────────────────────────────────────
 
-# These patterns mirror `media_analysis._parse_loudness`. The duplication is deliberate
-# — this module stays importable without pulling in the analysis engine — and a test
-# asserts both parsers agree on the same ffmpeg output, so the copy cannot drift.
-_INTEGRATED_RE = r"I:\s*(-?\d+(?:\.\d+)?)\s*LUFS"
-_LRA_RE = r"LRA:\s*(-?\d+(?:\.\d+)?)\s*LU"
-_PEAK_RE = r"Peak:\s*(-?\d+(?:\.\d+)?)\s*dBFS"
-
-
-def parse_loudness(stderr: str) -> Dict[str, Optional[float]]:
-    """Pull the ebur128 summary out of ffmpeg's stderr.
-
-    Scoped to the text after `Summary:`, with ebur128's per-frame progress lines removed.
-    Both steps are needed and neither is enough alone: the progress line carries its own
-    `I:` and `LRA:`, so a plain last-match-wins parse is right only because the summary
-    happens to print last, and scoping to the summary still swallows any progress line
-    that prints after it. Progress lines are identified by the `TARGET:` field, which
-    appears on every one of them and on nothing in the summary block.
-    """
-    marker = stderr.rfind("Summary:")
-    scope = "\n".join(
-        line for line in (stderr[marker:] if marker >= 0 else stderr).splitlines()
-        if "TARGET:" not in line
-    )
-
-    def latest(pattern: str) -> Optional[float]:
-        matches = re.findall(pattern, scope)
-        return float(matches[-1]) if matches else None
-
-    return {
-        "integrated_lufs": latest(_INTEGRATED_RE),
-        "loudness_range_lu": latest(_LRA_RE),
-        "true_peak_dbtp": latest(_PEAK_RE),
-    }
+# Parsing lives in `loudness_parse`, imported by both this module and the analysis
+# engine. Two copies of the same three regexes were carried here so this module stayed
+# importable without the engine; that argument covers the ENGINE, not the parsing rule,
+# and a rule that has to be right in two places is one that eventually is not.
+parse_loudness = loudness_parse.parse_loudness
 
 
 def _run(args: Sequence[str], *, stdin_bytes: Optional[bytes] = None) -> Tuple[int, bytes, str]: