feat(audio): a rough mix that measures what it achieved

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. Missing was the step between measuring and grading: deciding the
gains.

Adds `media_analysis mix_plan`, `measure_loudness`, and
`mix_plan_capabilities`. mix_plan derives the dialogue-normalisation gain, a
music-bed level relative to it, and ducking windows 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.

What makes it worth having:

- The achieved loudness is MEASURED. The premix is rendered, then re-measured;
  `achieved` carries integrated LUFS, true peak, 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 measuring 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 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, not a second copy of the same table.

The loudness parser reads the Summary block AND drops ebur128's per-frame
progress lines, which carry their own I: and LRA:. Last-match-wins 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 is a rough mix — gain staging, a bed, ducking. No EQ, compression,
de-essing or limiting, and capabilities() says so rather than leaving it
implied.

Release 2.102.0. Suite 2889 -> 2924. Three mutations (silent peak
normalisation, trimming a dialogue-gated standard, dropping the parser
scoping) were each caught; the parser one only after the test was
strengthened, since the first version passed with and without the fix.

Author: samuelgursky

.claude/skills/resolve-audio/SKILL.md

@@ -12,6 +12,20 @@ Thin router; depth stays in the kernel.
 - **Offline planning + bus routing** — `resolve-advanced/README.md` →
   `audio_plan`, `fairlight`, `audio`.
 
+## Rough mix before anything else
+
+If the ask is "make this sound balanced" rather than "route these buses", start with
+`media_analysis mix_plan` (Python server, no Resolve needed). Give it the dialogue stems
+and it derives the dialogue-normalisation gain, the music-bed level under it, and ducking
+windows from the dialogue's own silence — then renders a premix and **measures it**, so
+what you report is the loudness achieved rather than the gain arithmetic.
+
+`dry_run` defaults to true: show the gains and the window count first. On a
+full-programme standard (`ebu_r128`, `web`) a measured programme trim lands the whole mix
+on target; on `ott_dialogue_gated` it deliberately does not trim, because dialogue is the
+figure being graded. Flags (`loudness_off_target`, `true_peak_over`, `clipped`) come back
+with remedies and are never auto-corrected — report them, do not paper over them.
+
 ## Two servers — plan/measure offline, apply live
 
 | Job | Server | Tools |

CHANGELOG.md

@@ -2,6 +2,65 @@
 
 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

README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.101.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)

README.zh-CN.md

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

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.

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

install.py

@@ -37,7 +37,7 @@
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.101.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-lock.json

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

package.json

@@ -87,7 +87,7 @@
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.101.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()}")