davinci-resolve-mcp 2.103.0 → 2.103.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.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.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-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.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-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.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/install.py

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

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.103.0"
+VERSION = "2.103.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 353-tool granular server instead
 """
 
-VERSION = "2.103.0"
+VERSION = "2.103.1"
 
 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]: