davinci-resolve-mcp 2.219.0 → 2.221.0

package/CHANGELOG.md

@@ -2,6 +2,102 @@
 
 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.221.0 — native Resolve 21.1 audio level normalization
+
+Contributed by @legionsound (#214), live-validated on Studio 21.1.0.14.
+
+### Added
+
+- **`timeline normalize_audio_level`**, with the granular twin
+  `normalize_timeline_audio_level`, calling native 21.1 `NormalizeAudioLevel`
+  on explicit audio timeline item IDs. All four `NormalizeAudioOptions` fields
+  are supported — `normalizationMode`, `targetLevel` in dBFS, `targetLoudness`
+  in LKFS and `setLevelMode` — with either documented constant names or
+  integral native values. Every ID resolves before anything is written;
+  duplicate or missing IDs and malformed options are refused with nothing
+  changed. A native `false` stays `false`, and native defaults stay native
+  defaults rather than being pre-filled by the wrapper.
+- Registered in **both** write tables with a 21.1 callable-method floor,
+  destructive granular annotations and compound dry-run refusal tests. Tool
+  count 373 → 374.
+- **Source audio files are untouched** — this writes clip levels on the
+  timeline, not the media on disk.
+
+### Validation
+
+- Full suite green: 3,461 passed, 1 skipped. `timeline.normalize_audio_level`
+  probed directly: MEDIUM / destructive / recognised in the classifier, and
+  present in the destructive registry.
+- Live evidence is @legionsound's on Studio 21.1.0.14, and it is measured from
+  the **exported audio** rather than from a readback — independent FFmpeg
+  analysis of WAVs the wrappers actually produced: relative peak normalization
+  to −6 dBFS preserved the source 12 dB difference (−6.0 / −18.0 dBFS),
+  independent peak normalization measured −6.0 / −6.0 dBFS, and an EBU R128
+  target of −23 LKFS measured −22.9 LUFS, within 0.1 LU. Complete decoded PCM
+  was identical between both interfaces in every case. Not reproduced here;
+  this machine is Studio 19.1.3.7, below the 21.1 floor.
+- **Not claimed**: other normalization modes, difficult true-peak limiting,
+  multichannel routing, long programs and other source formats.
+
+### Changed
+
+- Adapted on merge, the same way #213 was. The branch was rebased onto
+  v2.219.0, so its 370 → 371 count bump and every generated agent-rule file
+  collided with the 373 that output blanking had landed. Counts resolved to
+  **374**, confirmed independently by the agent-rule generator, and the
+  generated files regenerated rather than hand-merged. No behaviour changed in
+  the adaptation.
+
+## What's New in v2.220.0 — native Resolve 21.1 output blanking, timeline and clip
+
+Contributed by @legionsound (#213), live-validated on Studio 21.1.0.14.
+
+### Added
+
+- **`timeline set_output_blanking`** and **`timeline_item set_output_blanking`**,
+  with granular twins `set_timeline_output_blanking` and
+  `set_timeline_item_output_blanking`, calling native 21.1 `SetOutputBlanking`.
+  `Top`/`Bottom`/`Left`/`Right` are **native pixel coordinates, not independent
+  margin widths** — the wrapper says so rather than letting the names imply
+  otherwise. Whole-valued native floats round-trip without conversion,
+  malformed values and unknown keys are refused, and no undocumented geometry
+  limits are invented.
+- **`timeline_item set_use_timeline_for_output_blanking`**, with the granular
+  twin `set_timeline_item_use_timeline_for_output_blanking`, as an explicit
+  inheritance switch.
+- **A clip override does not silently disable timeline inheritance.** Measured:
+  a clip write while inheritance was on returned false without changing
+  inheritance, and succeeded only after an explicit disable. The wrapper
+  preserves that native false instead of quietly flipping the switch on the
+  caller's behalf — a clip that stops inheriting is a change nobody asked for.
+- All three actions carry method floors, entries in **both** write-risk tables,
+  destructive granular annotations and dry-run refusal tests. Tool count 370 →
+  373.
+
+### Validation
+
+- Full suite green: 3,457 passed, 1 skipped. All six mutating actions added
+  across #209, #211 and #213 probed directly against the classifier and the
+  destructive registry — every one MEDIUM / destructive / recognised in both.
+- Live evidence is @legionsound's on Studio 21.1.0.14: both interfaces exported
+  synthetic red-clip PNGs with exact lit-pixel bounds — full `0/0/640/360`,
+  timeline `64/36/576/324`, clip `128/72/512/288`, restored inheritance
+  `64/36/576/324` — and a native partial write of `Top: 80.0` updated one
+  coordinate while preserving the others on readback. Recorded as sampled-frame
+  and readback results, **not** whole-movie or out-of-range behaviour claims.
+  Not reproduced here; this machine is Studio 19.1.3.7, below the 21.1 floor.
+
+### Changed
+
+- Adapted on merge. The branch was cut before #211, so its tool-count bump
+  (368 → 371) and every generated agent-rule file conflicted with the 370 that
+  multicam had landed. Counts were resolved to **373** — confirmed
+  independently by the agent-rule generator rather than by arithmetic alone —
+  and the generated files were regenerated instead of hand-merged, which is
+  the only resolution that cannot silently disagree with its source. Both
+  documentation pointers were kept. No behaviour was changed in the
+  adaptation.
+
 ## What's New in v2.219.0 — native Resolve 21.1 multicam creation and flattening
 
 Contributed by @legionsound (#211), live-validated on Studio 21.1.0.14.

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.219.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.221.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(370%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(374%20full)-blue.svg)](#server-modes)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
@@ -133,7 +133,7 @@ The command starts a loopback-only server and opens the control panel in your br
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
 | Compound | `src/server.py` | 36 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
-| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 370 | Power users who want one MCP tool per Resolve API method. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 374 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
 
@@ -365,7 +365,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **36** compound / **370** granular (live server) |
+| MCP Tools | **36** compound / **374** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |

package/README.zh-CN.md

@@ -2,17 +2,17 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.219.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.221.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(370%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(374%20full)-blue.svg)](#服务器模式)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#服务器模式)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![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.219.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.221.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -88,7 +88,7 @@ venv/bin/python -m src.control_panel
 | 模式 | 入口 | 工具数 | 适合谁 |
 |------|------|--------|--------|
 | Compound（复合） | `src/server.py` | 36 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
-| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 370 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 374 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -226,7 +226,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **36** 复合 / **370** 细粒度（实时服务器） |
+| MCP 工具 | **36** 复合 / **374** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -345,7 +345,7 @@ to the user as verified.
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
 | Compound (default) | `src/server.py` | 36 tools | Most workflows — keeps context lean |
-| Granular (full) | `src/server.py --full` | 370 tools | Power users needing one tool per API method |
+| Granular (full) | `src/server.py --full` | 374 tools | Power users needing one tool per API method |
 
 Resolve 21.1 adds [twelve read-only discovery controls](reference/resolve211-read-controls.md)
 for edition, presets, audio formats/codecs, normalization modes, speed, fades
@@ -2485,3 +2485,6 @@ Native Resolve 21.1 speed and fade setters: see [speed/fades](reference/resolve2
 Native 21.1 transition creation: see [transition controls](reference/resolve211-native-transitions.md) for options, item-index changes and contributor-rendered evidence.
 
 Native multicam creation and flattening: [21.1 controls](reference/resolve211-multicam.md), with contributor render evidence and remaining family coverage.
+Native timeline/clip output blanking: [21.1 controls](reference/resolve211-blanking.md), with explicit inheritance and pixel-bound evidence.
+
+Native audio normalization: [21.1 controls](reference/resolve211-normalization.md), with independently measured exported-audio evidence.

package/docs/contributing.md

@@ -64,7 +64,7 @@ davinci-resolve-mcp/
 ├── install.py                    # Universal installer (macOS/Windows/Linux)
 ├── src/
 │   ├── server.py                # Compound MCP server — 36 tools (default)
-│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 370 tools
+│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 374 tools
 │   ├── granular/                # Modular full-server implementation
 │   └── utils/                   # Platform detection, Resolve connection helpers
 ├── tests/                       # offline suite (test_*.py) + live harnesses (live_*.py):

package/docs/install.md

@@ -144,7 +144,7 @@ The MCP server comes in two modes:
 | Mode | File | Tools | Best For |
 |------|------|-------|----------|
 | **Compound** (default) | `src/server.py` | 36 | Most users — fast, clean, low context usage |
-| **Full** | `src/resolve_mcp_server.py` | 370 | Power users who want one tool per API method |
+| **Full** | `src/resolve_mcp_server.py` | 374 | Power users who want one tool per API method |
 
 The compound server's `timeline_item` tool includes dedicated actions for common workflows:
 
@@ -159,7 +159,7 @@ The compound server's `timeline_item` tool includes dedicated actions for common
 
 The installer uses the compound server by default. To use the full server:
 ```bash
-python src/server.py --full    # Launch full 370-tool server
+python src/server.py --full    # Launch full 374-tool server
 # Or point your MCP config directly at src/resolve_mcp_server.py
 ```
 

package/docs/reference/api-coverage.md

@@ -25,7 +25,7 @@ Every non-deprecated method in the bundled legacy README is represented. This
 does not claim complete coverage of the newer Resolve 21.1 typed API. The
 default compound server exposes **36 tools** that group related operations by
 action parameter, keeping LLM context windows lean. The full granular server
-provides **370 individual tools** for power users. The legacy coverage spans
+provides **374 individual tools** for power users. The legacy coverage spans
 13 API object classes. MCP-level kernel actions are tracked separately in
 [Kernel Action Coverage](../kernels/README.md).
 
@@ -635,3 +635,6 @@ Native speed and fade setters in both interfaces are documented in [Resolve 21.1
 Native 21.1 transition creation: see [transition controls](resolve211-native-transitions.md) for options, item-index changes and contributor-rendered evidence.
 
 Native multicam creation and flattening: [21.1 controls](resolve211-multicam.md), with contributor render evidence and remaining family coverage.
+Native timeline/clip output blanking: [21.1 controls](resolve211-blanking.md), with explicit inheritance and pixel-bound evidence.
+
+Native audio normalization: [21.1 controls](resolve211-normalization.md), with independently measured exported-audio evidence.

package/docs/reference/readwrite-symmetry.md

@@ -2,8 +2,8 @@
 
 # Read/Write Symmetry Audit
 
-- write-style action occurrences scanned: **121**
-- write-style action occurrences with a matching read: **73**
+- write-style action occurrences scanned: **124**
+- write-style action occurrences with a matching read: **76**
 - distinct high-signal `set_` actions without a direct/known readback: **4**
 
 ## High-signal gaps — `set_` with no direct/known readback

package/docs/reference/resolve211-blanking.md

@@ -0,0 +1,55 @@
+# Resolve 21.1 output blanking
+
+The native setters are exposed in both interfaces:
+
+| Compound tool/action | Granular tool |
+|---|---|
+| timeline set_output_blanking | set_timeline_output_blanking |
+| timeline_item set_output_blanking | set_timeline_item_output_blanking |
+| timeline_item set_use_timeline_for_output_blanking | set_timeline_item_use_timeline_for_output_blanking |
+
+Blanking setters take `options` containing one or more Top/Bottom/Left/Right
+pixel coordinates. These are bounds, not four independent margin widths. For a
+640x360 frame, full picture is Top0/Bottom360/Left0/Right640. Whole-valued floats
+from native getter results are accepted; fractional/non-finite values, booleans,
+unknown keys and empty dictionaries are refused. No undocumented geometry bounds
+are invented, and partial dictionaries are forwarded unchanged to Resolve.
+
+The inheritance setter requires a strict `use_timeline` boolean. To set a clip
+override, disable inheritance explicitly first. On the measured build, setting
+clip blanking while inheritance was enabled returned false and changed nothing.
+The wrapper preserves that failure and never silently changes inheritance.
+Re-enabling inheritance returns the clip to the timeline's blanking. Native
+getter payloads may be empty when the clip inherits timeline blanking.
+
+All three actions have 21.1 method floors, registered destructive MEDIUM-risk
+writes in both classifier tables, and destructive granular annotations. Explicit
+compound dry-run requests are refused before writes. Native failure is preserved
+as success:false. Clip locators use the existing 1-based tracks/0-based item
+indexes.
+
+## Contributor validation
+
+Contributor-validated on macOS Studio 21.1.0.14 using a generated solid red clip
+in a disposable 640x360 project, through both actual community interfaces.
+Resolve-exported PNGs showed exact lit-pixel bounds:
+
+- Full picture: left0/top0/right640/bottom360.
+- Timeline blanking: left64/top36/right576/bottom324.
+- Clip override: left128/top72/right512/bottom288.
+- Inheritance restored: timeline bounds64/36/576/324 again.
+
+The override frame was visually inspected; both interfaces returned the same
+bounds. Inherited clip-set refusal was also verified live. This is sampled-frame
+and readback evidence, not whole-movie verification, or proof of
+negative-coordinate, out-of-frame or audio-item behavior. A native-only partial
+update with Top80.0 also succeeded and preserved Bottom/Left/Right in readback;
+that extra case was not image-verified. Those cases are not
+claimed tested.
+
+`tests/live_resolve211_blanking.py OUTPUT_DIR` requires the disposable project
+Codex Blanking Validation 20260909 with one synthetic red.mov video clip, at
+640x360/24 fps with timeline start00:00:00:00. Generate red.mov using the color
+fixture in resolve211-native-transitions.md. The script invokes both wrappers,
+exports comparison PNGs and restores full timeline blanking/inheritance before
+saving the scratch project. Never substitute production media.

package/docs/reference/resolve211-normalization.md

@@ -0,0 +1,58 @@
+# Native Resolve 21.1 audio normalization
+
+Compound `timeline normalize_audio_level` and granular
+`normalize_timeline_audio_level` take explicit audio timeline `item_ids` and
+optional `options`. IDs are resolved on the current timeline's audio tracks,
+with no implicit linked-item expansion. Missing/duplicate IDs and malformed
+options are refused before the native write. Native false stays success:false.
+
+All NormalizeAudioOptions fields are supported:
+
+- normalizationMode: native name from get_normalize_audio_modes.
+- targetLevel: finite dBFS number, for example -6.
+- targetLoudness: finite LKFS number, for example -23.
+- setLevelMode: NORMALIZE_AUDIO_SET_LEVEL_RELATIVE or
+  NORMALIZE_AUDIO_SET_LEVEL_INDEPENDENT, or an integral native constant value.
+
+Names resolve against the live Resolve object. Unknown option keys, invalid
+named constants, booleans in numeric fields and non-finite values are rejected.
+Omitted options stay omitted; Resolve supplies its native defaults. Mode names
+are passed through rather than hard-coded into a stale list. Use the existing
+mode reader for the current build. The wrapper does not invent range clamps or
+turn a refused native normalization into success.
+
+The action has a 21.1 callable-method floor, entries in both destructive/risk
+tables (MEDIUM), destructive granular annotations, and explicit compound dry-run
+refusal. Normalization changes project clip gain, not source audio files.
+
+## Contributor audio evidence
+
+Contributor-validated on macOS Studio 21.1.0.14 in a disposable project using
+997 Hz synthetic stereo tones, with one source 12 dB quieter than the other.
+Both actual community interfaces produced byte-identical decoded PCM per case.
+Independent FFmpeg measurements of exported 24-bit/48 kHz WAVs:
+
+| Requested case | Measured output |
+|---|---|
+| Sample Peak Program, relative, target -6 dBFS | Two clip segments peak -6.0/-18.0 dBFS; 12 dB difference preserved |
+| Sample Peak Program, independent, target -6 dBFS | Both segments peak -6.0 dBFS |
+| EBU R128, target -23 LKFS, peak setting-1 dBFS | Integrated -22.9 LUFS, within 0.1 LU of requested target |
+
+These are exported-audio measurements, not just gain readback. They do not prove
+all normalization modes, true-peak limiting on difficult signals, long-program
+loudness, multichannel bus behavior, or different source formats.
+
+`tests/live_resolve211_normalization.py OUTPUT_DIR` requires disposable project
+Codex Normalization Validation 20260909 at 24 fps, with tone.wav and quiet.wav.
+The script creates timelines/renders and saves that project. Generate fixtures
+without production media:
+
+```sh
+ffmpeg -f lavfi -i 'sine=frequency=997:sample_rate=48000:duration=4' \
+  -af 'pan=stereo|c0=c0|c1=c0' -c:a pcm_s24le tone.wav
+ffmpeg -i tone.wav -af volume=-12dB -c:a pcm_s24le quiet.wav
+```
+
+Measure each four-second segment with volumedetect and the loudness case with
+ebur128. Compare full decoded PCM between interfaces. Pure tones are deliberate
+meter fixtures; this does not substitute for representative-program QA.

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.219.0"
+VERSION = "2.221.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
@@ -1543,7 +1543,7 @@ def verify_resolve_connection(python_path, api_path, lib_path):
 
 def print_banner():
     title = f"DaVinci Resolve MCP Server — Installer v{VERSION}"
-    subtitle = "36 compound · 370 full · 3 platforms"
+    subtitle = "36 compound · 374 full · 3 platforms"
     print()
     print(bold("  ╔══════════════════════════════════════════════════════╗"))
     print(bold(f"  ║{title:^54}║"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.219.0",
+  "version": "2.221.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.219.0"
+VERSION = "2.221.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/granular/resolve_211.py

@@ -1,4 +1,6 @@
 """Native Resolve 21.1 discovery and editing controls."""
+from src.utils.resolve211_normalization import normalize_audio
+from src.utils.resolve211_blanking import validate_blanking
 from src.utils.resolve211_multicam import create_multicam, resolve_constant, GRADES
 from src.utils.resolve211_edits import validate_edit_options, validate_transition_options, transition_result
 from src.granular.common import (
@@ -229,3 +231,63 @@ def flatten_timeline_item_multicam(grade_option: str = "FLATTEN_MULTICAM_COPY_GR
     if error:
         return {"error": error}
     return {"success": bool(item.FlattenMulticam(grade))}
+
+
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
+def set_timeline_output_blanking(options: dict) -> dict:
+    """Set native 21.1 timeline Top/Bottom/Left/Right pixel coordinates."""
+    error = validate_blanking(options)
+    if error:
+        return {"error": error}
+    _, tl, error = _get_timeline()
+    if error:
+        return error
+    missing = _requires_method(tl, "SetOutputBlanking", "21.1")
+    if missing:
+        return missing
+    return {"success": bool(tl.SetOutputBlanking(dict(options)))}
+
+
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
+def set_timeline_item_output_blanking(options: dict, track_type: str = "video", track_index: int = 1, item_index: int = 0) -> dict:
+    """Set native 21.1 clip pixel coordinates. Disable timeline blanking inheritance first; this call does not change inheritance."""
+    error = validate_blanking(options)
+    if error:
+        return {"error": error}
+    if track_type not in ("video", "audio") or track_index < 1 or item_index < 0:
+        return {"error": "Use video/audio, a 1-based track index and a non-negative item index"}
+    item, error = _get_timeline_item(track_type, track_index, item_index)
+    if error:
+        return error
+    missing = _requires_method(item, "SetOutputBlanking", "21.1")
+    if missing:
+        return missing
+    return {"success": bool(item.SetOutputBlanking(dict(options)))}
+
+
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
+def set_timeline_item_use_timeline_for_output_blanking(use_timeline: bool, track_type: str = "video", track_index: int = 1, item_index: int = 0) -> dict:
+    """Explicitly enable/disable native 21.1 timeline blanking inheritance for a clip."""
+    if type(use_timeline) is not bool:
+        return {"error": "use_timeline must be a boolean"}
+    if track_type not in ("video", "audio") or track_index < 1 or item_index < 0:
+        return {"error": "Use video/audio, a 1-based track index and a non-negative item index"}
+    item, error = _get_timeline_item(track_type, track_index, item_index)
+    if error:
+        return error
+    missing = _requires_method(item, "SetUseTimelineForOutputBlanking", "21.1")
+    if missing:
+        return missing
+    return {"success": bool(item.SetUseTimelineForOutputBlanking(use_timeline))}
+
+
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
+def normalize_timeline_audio_level(item_ids: list[str], options: dict | None = None) -> dict:
+    """Native 21.1 normalization of explicit audio timeline item IDs. Options normalizationMode, targetLevel (dBFS), targetLoudness (LKFS), setLevelMode; use get_normalize_audio_modes for names."""
+    _, timeline, error = _get_timeline()
+    if error:
+        return error
+    missing = _requires_method(timeline, "NormalizeAudioLevel", "21.1")
+    if missing:
+        return missing
+    return normalize_audio(get_resolve(), timeline, item_ids, {} if options is None else options)

package/src/resolve_mcp_server.py

@@ -34,7 +34,7 @@ from src.utils.update_check import start_background_update_check
 if __name__ == "__main__":
     try:
         start_background_update_check(VERSION, project_dir, logger)
-        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (370 granular tools)")
+        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (374 granular tools)")
         run_fastmcp_stdio(mcp)
     except KeyboardInterrupt:
         logger.info("Server shutdown requested")

package/src/server.py

@@ -8,10 +8,10 @@ Each tool groups related operations via an 'action' parameter.
 
 Usage:
     python src/server.py              # Start the MCP server
-    python src/server.py --full       # Start the 370-tool granular server instead
+    python src/server.py --full       # Start the 374-tool granular server instead
 """
 
-VERSION = "2.219.0"
+VERSION = "2.221.0"
 
 import base64
 import os
@@ -43,6 +43,8 @@ for p in [current_dir, project_dir]:
         sys.path.insert(0, p)
 
 from src.utils.resolve211_multicam import create_multicam, resolve_constant, GRADES
+from src.utils.resolve211_blanking import validate_blanking
+from src.utils.resolve211_normalization import normalize_audio
 from src.utils.resolve211_edits import validate_edit_options, validate_transition_options, transition_result
 
 # Platform-specific Resolve paths
@@ -25052,7 +25054,7 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
 
 
 _TIMELINE_ACTIONS = [
-    "get_normalize_audio_modes", "get_output_blanking",
+    "set_output_blanking", "normalize_audio_level", "get_normalize_audio_modes", "get_output_blanking",
     # Offline authoring — served without a Resolve connection, above the _check() gate.
     "author_offline", "offline_fallback_capabilities",
     "list", "get_current", "set_current", "get_name", "set_name", "get_start_frame",
@@ -25101,6 +25103,8 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     (resolve_control api_truth "GetSourceStartFrame").
 
     Actions:
+      set_output_blanking(options) -> {success} — native 21.1 pixel coordinates.
+      normalize_audio_level(item_ids, options?) -> {success} — native 21.1 normalization; audio timeline item IDs.
       get_normalize_audio_modes() -> {modes} — documented on Resolve 21.1+.
       get_output_blanking() -> {blanking} — documented on Resolve 21.1+. Pixel coordinates; empty on a clip inheriting timeline blanking.
       list() -> {timelines}
@@ -25419,6 +25423,21 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     if not tl:
         return _err("No current timeline")
 
+    if action == "normalize_audio_level":
+        missing = _requires_method(tl, "NormalizeAudioLevel", "21.1")
+        if missing:
+            return missing
+        return normalize_audio(get_resolve(), tl, p.get("item_ids"), {} if p.get("options") is None else p["options"])
+
+    if action == "set_output_blanking":
+        error = validate_blanking(p.get("options"))
+        if error:
+            return _err(error)
+        missing = _requires_method(tl, "SetOutputBlanking", "21.1")
+        if missing:
+            return missing
+        return {"success": bool(tl.SetOutputBlanking(dict(p["options"])))}
+
     if action == "get_normalize_audio_modes":
         missing = _requires_method(tl, "GetNormalizeAudioModes", "21.1")
         if missing:
@@ -26282,6 +26301,8 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
 
     Actions:
       flatten_multicam(grade_option?, ...) -> {success} — native 21.1, replaces multicam with its current angle.
+      set_output_blanking(options, ...) -> {success} — native 21.1; disable timeline inheritance first.
+      set_use_timeline_for_output_blanking(use_timeline, ...) -> {success} — explicit inheritance switch.
       add_transition(options, ...) -> {success, transition?} — native 21.1 transition; reports actual span.
       set_speed(options, ...) -> {success} — native 21.1 speed options; RippleTimeline defaults false.
       set_fades(options, ...) -> {success} — native 21.1 FadeIn/FadeOut integer frames.
@@ -26348,6 +26369,23 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
             return _err(error)
         return {"success": bool(item.FlattenMulticam(grade))}
 
+    if action == "set_output_blanking":
+        error = validate_blanking(p.get("options"))
+        if error:
+            return _err(error)
+        missing = _requires_method(item, "SetOutputBlanking", "21.1")
+        if missing:
+            return missing
+        return {"success": bool(item.SetOutputBlanking(dict(p["options"])))}
+
+    if action == "set_use_timeline_for_output_blanking":
+        if type(p.get("use_timeline")) is not bool:
+            return _err("use_timeline must be a boolean")
+        missing = _requires_method(item, "SetUseTimelineForOutputBlanking", "21.1")
+        if missing:
+            return missing
+        return {"success": bool(item.SetUseTimelineForOutputBlanking(p["use_timeline"]))}
+
     if action == "add_transition":
         options = p.get("options")
         error = validate_transition_options(options)
@@ -26569,7 +26607,7 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
             return _err(f"Invalid interpolation. Must be one of: {', '.join(valid)}")
         return {"success": bool(item.SetKeyframeInterpolation(p["property"], p["frame"], p["interpolation"]))}
 
-    return _unknown(action, ["flatten_multicam","add_transition","set_speed","set_fades","get_speed","get_fades","get_output_blanking","get_use_timeline_for_output_blanking","get_name","get_property","set_property","get_duration","get_start","get_end","get_source_start_frame","get_source_end_frame","get_source_start_time","get_source_end_time","get_left_offset","get_right_offset","set_clip_enabled","get_clip_enabled","update_sidecar","get_unique_id","get_media_pool_item","get_stereo_convergence","get_stereo_left_window","get_stereo_right_window","get_linked_items","get_track_type_and_index","get_source_audio_mapping","load_burnin_preset","set_name","get_voice_isolation_state","set_voice_isolation_state","get_retime","set_retime","get_transform","set_transform","get_crop","set_crop","get_composite","set_composite","get_audio","set_audio","get_keyframes","add_keyframe","modify_keyframe","delete_keyframe","set_keyframe_interpolation"])
+    return _unknown(action, ["set_output_blanking","set_use_timeline_for_output_blanking","flatten_multicam","add_transition","set_speed","set_fades","get_speed","get_fades","get_output_blanking","get_use_timeline_for_output_blanking","get_name","get_property","set_property","get_duration","get_start","get_end","get_source_start_frame","get_source_end_frame","get_source_start_time","get_source_end_time","get_left_offset","get_right_offset","set_clip_enabled","get_clip_enabled","update_sidecar","get_unique_id","get_media_pool_item","get_stereo_convergence","get_stereo_left_window","get_stereo_right_window","get_linked_items","get_track_type_and_index","get_source_audio_mapping","load_burnin_preset","set_name","get_voice_isolation_state","set_voice_isolation_state","get_retime","set_retime","get_transform","set_transform","get_crop","set_crop","get_composite","set_composite","get_audio","set_audio","get_keyframes","add_keyframe","modify_keyframe","delete_keyframe","set_keyframe_interpolation"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -32691,9 +32729,9 @@ if __name__ == "__main__":
     start_background_update_check(VERSION, project_dir, logger, env=_setup_update_env())
     _install_threaded_tool_dispatch(mcp)
 
-    # Support --full flag to run the 370-tool granular server instead
+    # Support --full flag to run the 374-tool granular server instead
     if "--full" in sys.argv:
-        logger.info("Starting full 370-tool granular server...")
+        logger.info("Starting full 374-tool granular server...")
         sys.argv = [arg for arg in sys.argv if arg != "--full"]
         from src.granular import mcp as granular_mcp
 

package/src/utils/destructive_hook.py

@@ -87,6 +87,8 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "execute_swap",
     }),
     "timeline": frozenset({
+        "set_output_blanking",
+        "normalize_audio_level",
         "delete_clips",
         "move_clips",
         "duplicate_clips",
@@ -138,6 +140,8 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "create_subtitles",
     }),
     "timeline_item": frozenset({
+        "set_output_blanking",
+        "set_use_timeline_for_output_blanking",
         "set_clip_enabled",
         "set_property",
         "set_name",

package/src/utils/execution_lifecycle.py

@@ -276,6 +276,11 @@ class RiskClassificationHook(LifecycleHook):
         # how the clip's edges render. Existing content altered, not deleted.
         ("media_pool", "create_multicam_clip"),
         ("timeline_item", "flatten_multicam"),
+        ("timeline", "set_output_blanking"),
+        ("timeline_item", "set_output_blanking"),
+        ("timeline_item", "set_use_timeline_for_output_blanking"),
+
+        ("timeline", "normalize_audio_level"),
         ("timeline_item", "add_transition"),
         ("timeline_item", "set_speed"),
         ("timeline_item", "set_fades"),

package/src/utils/resolve211_blanking.py

@@ -0,0 +1,17 @@
+"""Preserve native pixel coordinates without inventing undocumented geometry limits."""
+import math
+
+
+def validate_blanking(options):
+    if not isinstance(options,dict) or not options:
+        return 'options must be a non-empty dictionary'
+    if set(options)-{'Top','Bottom','Left','Right'}:
+        return 'Only Top, Bottom, Left and Right are accepted'
+    for value in options.values():
+        try:
+            valid = type(value) in (int,float) and math.isfinite(value) and int(value)==value
+        except OverflowError:
+            valid = False
+        if not valid:
+            return 'Blanking values must be finite whole-pixel coordinates'
+    return None

package/src/utils/resolve211_normalization.py

@@ -0,0 +1,42 @@
+"""Native normalization: validate explicit audio-item selection before writes."""
+import math
+
+
+def finite_number(value):
+    try:
+        return type(value) in (int,float) and math.isfinite(value)
+    except OverflowError:
+        return False
+
+
+def normalize_audio(r, timeline, item_ids, options):
+    if not isinstance(item_ids,list) or not item_ids or any(not isinstance(i,str) or not i for i in item_ids):
+        return {'error':'item_ids must be a non-empty list of audio timeline item unique IDs'}
+    if len(set(item_ids))!=len(item_ids):
+        return {'error':'item_ids must not contain duplicates'}
+    if not isinstance(options,dict) or set(options)-{'normalizationMode','targetLevel','targetLoudness','setLevelMode'}:
+        return {'error':'Unknown normalization options or non-dictionary options'}
+    normalized=dict(options)
+    for key,value in options.items():
+        if key=='normalizationMode':
+            if not isinstance(value,str) or not value.strip():
+                return {'error':'normalizationMode must be a non-empty native mode name'}
+        elif key=='setLevelMode':
+            if isinstance(value,str):
+                if value not in ('NORMALIZE_AUDIO_SET_LEVEL_RELATIVE','NORMALIZE_AUDIO_SET_LEVEL_INDEPENDENT'):
+                    return {'error':'Unknown setLevelMode constant'}
+                value=getattr(r,value,None)
+            if not finite_number(value) or int(value)!=value:
+                return {'error':'setLevelMode must be a documented constant name or integral native value'}
+            normalized[key]=value
+        elif not finite_number(value):
+            return {'error':key+' must be a finite number'}
+    wanted=set(item_ids);found={}
+    for index in range(1,timeline.GetTrackCount('audio')+1):
+        for item in timeline.GetItemListInTrack('audio',index) or []:
+            uid=item.GetUniqueId()
+            if uid in wanted:
+                found[uid]=item
+    if any(uid not in found for uid in item_ids):
+        return {'error':'One or more IDs were not found on audio tracks; no normalization performed'}
+    return {'success':bool(timeline.NormalizeAudioLevel([found[uid] for uid in item_ids],normalized))}

package/src/utils/resolve_versions.py

@@ -227,6 +227,11 @@ _EVIDENCE_GATES: List[Dict[str, Any]] = [
 CODE_FLOORS: Dict[str, str] = {
     "MediaPool.CreateMulticamClip": "21.1",
     "TimelineItem.FlattenMulticam": "21.1",
+    "Timeline.SetOutputBlanking": "21.1",
+    "TimelineItem.SetOutputBlanking": "21.1",
+    "TimelineItem.SetUseTimelineForOutputBlanking": "21.1",
+
+    "Timeline.NormalizeAudioLevel": "21.1",
     "TimelineItem.AddTransition": "21.1",
     "TimelineItem.SetSpeed": "21.1",
     "TimelineItem.SetFades": "21.1",