davinci-resolve-mcp 2.100.0 → 2.102.0

package/CHANGELOG.md

@@ -2,6 +2,126 @@
 
 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.102.0
+
+**A rough mix that reports what it achieved, not what it intended.** The pieces were
+already here — `media_analysis` measures EBU R128 loudness and detects silence,
+`delivery_targets` holds the standards, `loudness_qc` grades a finished file. What was
+missing is the step between measuring and grading: deciding the gains.
+
+### Added
+
+- **`media_analysis mix_plan`** — dialogue-normalisation gain, a music-bed level relative
+  to it, and ducking windows derived from silence detection **on the dialogue stem**, so
+  the bed follows the words rather than a hand-placed envelope. `dry_run` defaults to
+  true and renders nothing.
+  - **The achieved loudness is measured, not derived.** The premix is rendered, then
+    re-measured; `achieved` carries integrated LUFS, true peak, loudness range, and the
+    delta from target. A plan that hits its target on paper and clips on true peak is a
+    failed plan, and only the measurement tells you which one you have.
+  - **Dialogue-anchored, then programme-trimmed.** Anchoring dialogue at target is right
+    for a dialogue-gated standard and wrong for a full-programme one the moment a bed is
+    added. For non-dialogue-gated standards one measured trim is applied to everything
+    equally — preserving the dialogue-to-bed relationship — and reported as
+    `program_normalize.trim_db`. It never runs on a dialogue-gated standard, where
+    dialogue is the figure being graded.
+  - **Nothing else is corrected.** `loudness_off_target`, `true_peak_over`, and `clipped`
+    come back as flags with remedies, never as a quietly normalised file.
+  - Standards come from `delivery_targets` (`web`, `podcast`, `ebu_r128`, `atsc_a85`,
+    `ott_dialogue_gated`) — the table the delivery tools already grade against, not a
+    second copy.
+- **`media_analysis measure_loudness`** — integrated LUFS, loudness range, and true peak
+  per file.
+- **`media_analysis mix_plan_capabilities`** — dependency state, known standards, and the
+  defaults, including the music-bed offset, which is the number most likely to be argued
+  with and so is named rather than buried.
+
+### Fixed while building it
+
+The new loudness parser reads the `Summary:` block **and** drops ebur128's per-frame
+progress lines, which carry their own `I:` and `LRA:` fields. A plain last-match-wins
+parse is correct only because ffmpeg happens to print the summary last, and scoping to
+the summary alone still swallows a progress line printed after it. Both steps are needed;
+a test with a trailing progress line pins it.
+
+### Scope
+
+A rough mix: gain staging, a bed, and ducking. No EQ, compression, de-essing, or
+limiting, and the module says so in its capabilities rather than leaving it implied.
+
+### Validation
+
+- Offline suite: 2924 passed, 1 skipped, 711 subtests, 0 failures.
+- End-to-end through real ffmpeg on generated tones: target hit from measurement, the
+  programme trim landing a hot bed on R128, a dialogue-gated standard refusing the trim,
+  and clipping reported rather than normalised away.
+- Three deliberate mutations (silent peak normalisation, trimming a dialogue-gated
+  standard, and dropping the parser scoping) were each caught. The parser mutation was
+  caught only after the test was strengthened — the first version of it passed against
+  both the fix and its absence.
+- No Resolve behavior changed; live test not required.
+
+## What's New in v2.101.0
+
+**A grade can now reject itself.** `assess_grade` has measured grade damage since
+v2.68.0 — banding in a sky, highlight levels collapsing, shadow grain amplified into
+noise — and every flag it raises carries a remedy. Nothing consumed that report. The
+measurement existed; the loop did not, so the remedy "reduce the strength" was advice an
+agent had no way to act on.
+
+### Added
+
+- **`media_analysis grade_loop`** — the retry ladder. Applies a look LUT, measures the
+  real decoded frame, and on any flag retries with the same look attenuated toward
+  identity (strength x 0.8 per rung, floored at 0.5, three tries by default). The first
+  strength that clears every sampled frame wins.
+  - **A flagged result is never reported acceptable.** An exhausted ladder returns
+    `needs_human` with the best attempt and its remaining flags — never a quiet success
+    at a strength that still bands.
+  - **Every sampled frame must pass.** `times=[...]` samples several timestamps and the
+    report names the one that failed; a grade clean on the frame you happened to check
+    is not a grade that passed.
+  - **The best attempt is the gentlest.** When nothing converges, attempts rank by flag
+    count with ties broken by the smallest colour shift — equal damage means taking the
+    one a human has less to undo.
+  - **It does not touch the project.** The result is an apply manifest with
+    `safe_to_apply`, and a flagged result carries the reason it is blocked.
+  - `dry_run` defaults to true and reports the ffmpeg decode budget before anyone
+    commits to it. `cost_tier` defaults to `numeric`, because escalating every rung to
+    vision would spend host turns on attempts that exist to be rejected.
+- **`media_analysis grade_loop_capabilities`** — dependency state, ladder constants, and
+  an explicit statement of which modes exist.
+- **`src/utils/cube_lut.py`** — read, write, and attenuate 3D `.cube` LUTs. Attenuation
+  is a blend toward identity, the same operation a LUT mix control performs. Exact at
+  both endpoints: strength 1.0 returns the table unchanged and 0.0 returns true
+  identity. 1D LUTs are refused by name, and attenuation on a non-unit
+  `DOMAIN_MIN`/`DOMAIN_MAX` is refused because identity is only identity on 0..1.
+
+### Not built, and said so
+
+The in-loop **live** mode — apply in Resolve, render a frame, assess, repeat — is not
+implemented. It needs a single-frame render per rung, and shipping it unvalidated would
+put a "verified live" claim behind something no runnable command has produced.
+`grade_loop_capabilities()` says this in the response rather than only in the docs. The
+offline LUT ladder is complete and validated.
+
+### Documentation
+
+- `docs/guides/color-decision-guide.md` — a new "Rejecting Your Own Grade" section on
+  when measurement beats eyeballing a compressed preview.
+- `docs/kernels/color-grade-kernel.md` — the numeric grade-QC actions and their
+  display-referred-only contract.
+
+### Validation
+
+- Offline suite: 2889 passed, 1 skipped, 711 subtests, 0 failures.
+- End-to-end through real ffmpeg on generated media: a look that converges only after
+  backing off, and one that never converges and says so.
+- Two deliberate mutations — `acceptable` hard-coded true, and a rung passing on its
+  first clean frame — were each caught by the new tests.
+- No Resolve behavior changed; live test not required. A test asserts no Resolve
+  connection is attempted.
+
 ## What's New in v2.100.0
 
 **The craft guidance is now readable by any MCP client.** This repository carries a

package/README.md

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

package/docs/SKILL.md

@@ -552,6 +552,13 @@ Key actions:
   `load_user_preferences_preset`
 - `quit` — terminates Resolve (destructive; confirm with user first)
 
+**Offline audio and image QC on `media_analysis`** — no Resolve connection required:
+`measure_loudness`, `mix_plan` / `mix_plan_capabilities` (dialogue-anchored rough mix
+with dialogue-following ducking, rendered and re-measured), and `assess_grade` /
+`grade_loop` / `grade_loop_capabilities` (numeric grade-damage QC and the retry ladder
+that backs a look off until it stops damaging the picture). See
+`docs/kernels/audio-fairlight-kernel.md` and `docs/kernels/color-grade-kernel.md`.
+
 **`layout_presets`** — Save, load, export, import, delete UI layout presets.
 `list` (Resolve 21.0.4+) enumerates the saved preset names the other actions
 take.

package/docs/guides/color-decision-guide.md

@@ -211,6 +211,36 @@ If untreated/current/after comparison is not available through the API in the
 moment, say which part is unavailable and whether the user wants a blind/global
 pass. Do not imply that a grade was reviewed if no rendered frames were checked.
 
+## Rejecting Your Own Grade
+
+Looking at frames tells you whether a grade reads right. It does not reliably tell you
+whether it *damaged* the picture — banding in a sky, highlight levels collapsing, shadow
+grain amplified into visible noise. Those are measurable, and measuring them is cheaper
+and steadier than eyeballing a compressed preview.
+
+`media_analysis assess_grade` measures one graded frame against its source and returns
+flags with remedies. `media_analysis grade_loop` closes the loop: it applies a look LUT,
+measures the real decoded result, and on any flag retries with the same look attenuated
+toward identity (strength × 0.8 per rung, floored at 0.5, three tries by default). The
+first strength that clears every sampled frame wins.
+
+Three properties matter more than the convenience:
+
+- **A flagged result is never reported acceptable.** When the ladder is exhausted the
+  answer is `needs_human`, carrying the best attempt and what it still fails on. There
+  is no strength at which the loop shrugs and ships.
+- **Every sampled frame must pass.** Pass several timestamps — a grade that is clean on
+  the frame you happened to check and bands two hundred frames later has not passed
+  anything. The report names the frame that failed.
+- **It does not touch the project.** The loop returns an apply manifest and stops.
+  Applying a grade is still a deliberate, version-protected step, and a result carrying
+  unresolved flags should reach a human before it reaches a timeline.
+
+Reach for it when applying an unfamiliar look LUT to unfamiliar footage, which is
+exactly where "it looked fine on the first shot" goes wrong. The flags are advisory
+thresholds, not standards — the raw measurements come back too, so a colorist can
+disagree with the flag rather than only with the verdict.
+
 ## Safe Color Workflow
 
 Before changing color:

package/docs/kernels/audio-fairlight-kernel.md

@@ -53,6 +53,39 @@ All kernel actions are exposed through `timeline`.
 - Subtitle generation from the generated timeline returned true.
 - Fairlight preset listing and the full boundary report worked.
 
+## Rough mix (`media_analysis`)
+
+Offline and file-based — no Resolve connection — sitting between measuring loudness and
+grading it against a spec. The step nothing else covered was deciding the gains.
+
+- `measure_loudness(path|paths)` — integrated LUFS, loudness range, and true peak per
+  file via ffmpeg `ebur128`.
+- `mix_plan(dialogue[], music?, sfx?, standard?, target_lufs?, bed_offset_lu?, duck_db?,
+  attack_s?, release_s?, hold_s?, dry_run?, output_path?, program_normalize?)` —
+  dialogue-normalisation gain, a bed level relative to it, and ducking windows derived
+  from silence detection **on the dialogue stem**, so the bed follows the words rather
+  than a hand-placed envelope. `dry_run` defaults to true and renders nothing.
+- `mix_plan_capabilities()` — dependency state, the standards it knows, and the defaults.
+
+Three things worth knowing before using it:
+
+- **The achieved loudness is measured, not derived.** The premix is rendered, then
+  re-measured, and `achieved` carries what came back. A plan that hits its target on
+  paper and clips on true peak is a failed plan; only the measurement distinguishes them.
+- **Dialogue-anchored, then programme-trimmed.** Anchoring dialogue at target is right
+  for a dialogue-gated standard and wrong for a full-programme one the moment a bed is
+  added. For non-dialogue-gated standards a single measured trim is applied to everything
+  equally — preserving the dialogue-to-bed relationship — and reported as
+  `program_normalize.trim_db`. It never runs on a dialogue-gated standard.
+- **Nothing else is corrected.** Over true peak or clipped comes back as a flag with a
+  remedy, never as a quietly normalised file. Pulling the mix down to fix a peak would
+  move the loudness off the target it just hit.
+
+Standards come from `src/utils/delivery_targets.py` (`web`, `podcast`, `ebu_r128`,
+`atsc_a85`, `ott_dialogue_gated`) — the same table the delivery tools grade against, not
+a second copy. It is a rough mix: gain staging, a bed, and ducking. No EQ, compression,
+de-essing, or limiting.
+
 ## Boundaries
 
 - Timeline item audio properties may be readable as `None` and can reject writes

package/docs/kernels/color-grade-kernel.md

@@ -67,6 +67,28 @@ All actions are exposed through `timeline_item_color`.
   and delete worked.
 - Gallery capability and album list/create calls worked.
 
+## Numeric grade QC (`media_analysis`)
+
+Not part of the live kernel — no Resolve connection is involved — but it belongs to the
+same decision. Both actions measure a decoded frame of the real result, never a
+simulated transform, because LUT interpolation and encode rounding are where banding is
+actually introduced.
+
+- `assess_grade(source_path, time_seconds, graded_path|lut_path, working_space)` —
+  flags (`flat`, `washed_out`, `milky`, `noisy`, `clipped`, `posterized`, `banding`),
+  each with a remedy, plus the raw tonal/noise/damage measurements.
+- `grade_loop(source_path, lut_path, times[], strength?, max_tries?, strength_floor?,
+  dry_run?)` — the retry ladder over `assess_grade`. Attenuates the look toward identity
+  until every sampled frame clears, or returns `needs_human` with the best attempt.
+  `dry_run` defaults to **true** and reports the ffmpeg decode budget first.
+- `grade_loop_capabilities()` — dependency state, ladder constants, and which modes
+  exist. The in-loop **live** mode (apply in Resolve, render, assess) is **not built**;
+  the loop returns an apply manifest instead of driving the project.
+
+Both are display-referred only. Log and scene-referred encodings run through the same
+arithmetic happily and produce meaningless numbers, so `working_space` must be declared
+and non-display-referred values are refused rather than guessed at.
+
 ## Boundaries
 
 - Node graph internals are intentionally limited by Resolve's public API. The

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.100.0"
+VERSION = "2.102.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.100.0",
+  "version": "2.102.0",
   "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.100.0"
+VERSION = "2.102.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.100.0"
+VERSION = "2.102.0"
 
 import base64
 import os
@@ -20076,6 +20076,104 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
                     "metrics are undefined on them and will not be guessed at."
                 ),
             )
+    if action == "grade_loop":
+        # The retry ladder that consumes assess_grade's own verdict: apply the look,
+        # measure the real decoded frame, and on any flag retry with the look
+        # attenuated toward identity. Exhausting the ladder returns needs_human with
+        # the best attempt — never a quiet success at a strength that still bands.
+        from src.utils import grade_loop as _grade_loop_mod
+
+        source = str(p.get("source_path") or p.get("sourcePath") or "")
+        lut = str(p.get("lut_path") or p.get("lutPath") or "")
+        err, _clean = _validate_params(
+            {"source_path": source, "lut_path": lut},
+            {
+                "source_path": {"type": str, "required": True, "non_empty": True},
+                "lut_path": {"type": str, "required": True, "non_empty": True},
+            },
+        )
+        if err:
+            return _err(err)
+        kwargs = dict(
+            times=p.get("times"),
+            time_seconds=p.get("time_seconds", p.get("timeSeconds")),
+            strength=float(p.get("strength", 1.0) or 1.0),
+            max_tries=int(p.get("max_tries", p.get("maxTries", _grade_loop_mod.DEFAULT_MAX_TRIES))),
+            strength_floor=float(
+                p.get("strength_floor", p.get("strengthFloor", _grade_loop_mod.DEFAULT_STRENGTH_FLOOR))
+            ),
+            working_space=str(p.get("working_space") or p.get("workingSpace") or "rec709"),
+            cost_tier=str(p.get("cost_tier") or p.get("costTier") or _grade_loop_mod.DEFAULT_COST_TIER),
+        )
+        try:
+            # Dry run by default: the ladder can spend a dozen ffmpeg decodes per clip,
+            # and the plan names that budget before anyone commits to it.
+            if p.get("dry_run", True):
+                return _ok(**_grade_loop_mod.plan(source, lut, **kwargs))
+            return _ok(**_grade_loop_mod.run(
+                source, lut,
+                output_dir=(p.get("output_dir") or p.get("outputDir")) or None,
+                **kwargs,
+            ))
+        except (_grade_loop_mod.GradeLoopError, _grade_loop_mod.cube_lut.CubeLutError) as exc:
+            return _err(str(exc), code="GRADE_LOOP_REFUSED", category="invalid_input",
+                        remediation=(
+                            "Supply an existing source_path and a 3D .cube lut_path, plus "
+                            "times=[seconds,...] to sample. A grade clean on one frame is "
+                            "not a grade that passed."
+                        ))
+        except _grade_loop_mod.image_qc.ImageQcError as exc:
+            return _err(str(exc), code="IMAGE_QC_REFUSED", category="invalid_input")
+    if action == "grade_loop_capabilities":
+        from src.utils import grade_loop as _grade_loop_mod
+
+        return _ok(**_grade_loop_mod.capabilities())
+    if action in {"mix_plan", "measure_loudness", "mix_plan_capabilities"}:
+        # Gain staging between measuring loudness and grading it: dialogue-norm gain,
+        # a bed level relative to it, and ducking windows the dialogue itself implies.
+        # The render is measured afterwards, so what comes back is the loudness
+        # achieved rather than the arithmetic meant to produce it.
+        from src.utils import mix_plan as _mix_plan_mod
+
+        if action == "mix_plan_capabilities":
+            return _ok(**_mix_plan_mod.capabilities())
+        try:
+            if action == "measure_loudness":
+                paths = p.get("paths") or ([p["path"]] if p.get("path") else [])
+                if not paths:
+                    return _err("measure_loudness requires path or paths")
+                return _ok(measurements=[_mix_plan_mod.measure(str(item)) for item in paths])
+
+            dialogue = p.get("dialogue") or ([p["path"]] if p.get("path") else [])
+            if isinstance(dialogue, str):
+                dialogue = [dialogue]
+            kwargs = dict(
+                music=p.get("music") or [],
+                sfx=p.get("sfx") or [],
+                standard=str(p.get("standard") or _mix_plan_mod.DEFAULT_STANDARD),
+                target_lufs=(
+                    float(p["target_lufs"]) if p.get("target_lufs") is not None else None
+                ),
+                bed_offset_lu=float(p.get("bed_offset_lu", _mix_plan_mod.DEFAULT_BED_OFFSET_LU)),
+                duck_db=float(p.get("duck_db", _mix_plan_mod.DEFAULT_DUCK_DB)),
+                attack_s=float(p.get("attack_s", _mix_plan_mod.DEFAULT_ATTACK_S)),
+                release_s=float(p.get("release_s", _mix_plan_mod.DEFAULT_RELEASE_S)),
+                hold_s=float(p.get("hold_s", _mix_plan_mod.DEFAULT_HOLD_S)),
+            )
+            if p.get("dry_run", True):
+                return _ok(**_mix_plan_mod.plan(dialogue, **kwargs))
+            return _ok(**_mix_plan_mod.render(
+                dialogue,
+                output_path=(p.get("output_path") or p.get("outputPath")) or None,
+                program_normalize=p.get("program_normalize"),
+                **kwargs,
+            ))
+        except _mix_plan_mod.MixPlanError as exc:
+            return _err(str(exc), code="MIX_PLAN_REFUSED", category="invalid_input",
+                        remediation=(
+                            "Supply dialogue=[...] stems that carry audio. The mix is "
+                            "anchored to dialogue, so it cannot be planned without one."
+                        ))
     if action == "image_qc_capabilities":
         from src.utils import image_qc as _image_qc_mod
 
@@ -21028,6 +21126,11 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "capabilities",
         "recheck_capabilities",
         "assess_grade",
+        "grade_loop",
+        "grade_loop_capabilities",
+        "mix_plan",
+        "mix_plan_capabilities",
+        "measure_loudness",
         "image_qc_capabilities",
         "install_guidance",
         "resolve_output_root",