davinci-resolve-mcp 4.9.0 → 4.9.1

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 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 v4.9.1 — a rejected audio level write now says why, and what to do instead
+
+### Changed
+
+- **`safe_set_audio_properties` and `timeline_item set_audio` explain a
+  refused Volume / Pan / EQ write.** Resolve's scripting API has no write path
+  for audio clip or track level — `SetProperty('Volume'/'Level'/'Gain')`
+  returned `False` when measured live on 21.0.0, and `'Pan'` is the *video* transform
+  key, so it returns `True` while the audio pan does not move. A caller who saw
+  `{"write": false}` (or a `Pan` that "succeeded" and changed nothing) had no
+  way to tell "bad value" from "this cannot be written from the API at all" —
+  and the second is a different task. Both actions now attach a
+  `known_limitation` block when a level or EQ write fails, and on every `Pan`
+  write (its success is the misleading case): the
+  `api_truth` ledger entry plus the concrete ways around it (bake the gain into
+  a rendered copy of the source with ffmpeg; or save the mix once as a
+  Fairlight preset and apply it per-timeline with
+  `project_settings apply_fairlight_preset`, on Resolve 20.2.2+ only; the
+  preset methods are absent on 19.x). `AudioSyncOffset` writes are
+  unaffected — they work, and are not flagged. The legacy granular
+  `set_timeline_item_audio` returns the same guidance as its failure string.
+  Contributed by @youssefm3208-jpg (#279).
+
+### Changed on landing
+
+- A `Volume` / `Level` / `Gain` / EQ write is flagged only when Resolve
+  refused it, so a build that honours the write is not told it is impossible.
+- The Fairlight-preset workaround names its Resolve 20.2.2 floor.
+
+### Tests
+
+- `tests/test_audio_fairlight_probe.py`: a refused Volume write carries the
+  ledger entry and workarounds; a Pan write is flagged even when it returns
+  True; `AudioSyncOffset` is not flagged; an honoured Volume write is not
+  flagged; the preset workaround states its version floor.
+
+### Validation
+
+- Response-shape change only; no Resolve scripting call changed, so no live
+  run was required. The Volume/Pan behaviour is the `api_truth` ledger's live
+  measurement on 21.0.0.
+
 ## What's New in v4.9.0 — bounded Media Pool import
 
 ### Added

package/README.md

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

package/README.zh-CN.md

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

package/docs/SKILL.md

@@ -1787,6 +1787,10 @@ helpers:
 - `probe_audio_track(track_index?)`
 - `probe_audio_item(track_type?, track_index?, item_index?)`
 - `safe_set_audio_properties(properties, restore?, dry_run?, track_type?, track_index?, item_index?)`
+  — Volume / Pan / EQ writes are not honoured by Resolve's API; a request for
+  any of them returns a `known_limitation` block with the workaround (bake gain
+  into a rendered copy, or apply a Fairlight preset). `AudioSyncOffset` writes
+  do work.
 - `audio_mix_capability_report(...)`
 - `voice_isolation_capabilities(track_index?, track_type?, item_index?)`
 - `audio_mapping_report(clip_ids?)`
@@ -1911,7 +1915,9 @@ Key actions:
 - `get_transform` / `set_transform(Pan?, Tilt?, ZoomX?, ZoomY?, RotationAngle?, ...)`
 - `get_crop` / `set_crop(CropLeft?, CropRight?, CropTop?, CropBottom?, ...)`
 - `get_composite` / `set_composite(Opacity?, CompositeMode?)`
-- `get_audio` / `set_audio(Volume?, Pan?, AudioSyncOffset?)`
+- `get_audio` / `set_audio(Volume?, Pan?, AudioSyncOffset?)` — Resolve ignores
+  Volume / Pan / EQ writes on audio (returns a `known_limitation` block); only
+  `AudioSyncOffset` / `AudioSyncOffsetIsManual` take effect
 - `get_voice_isolation_state` / `set_voice_isolation_state(state)` — Resolve
   20.1+; audio timeline items only
 - `get_keyframes(property)`, `add_keyframe(property, frame, value)`,

package/install.py

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

package/src/granular/common.py

@@ -91,7 +91,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.9.0"
+VERSION = "4.9.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/granular/timeline_item.py

@@ -716,7 +716,17 @@ def set_timeline_item_audio(timeline_item_id: str,
             
             return f"Successfully set {' and '.join(changes)} for timeline item '{timeline_item.GetName()}'"
         else:
-            return f"Failed to set some audio properties for timeline item '{timeline_item.GetName()}'"
+            return (
+                f"Failed to set audio properties for timeline item "
+                f"'{timeline_item.GetName()}'. Resolve's scripting API has no "
+                "write path for audio level, pan, or EQ — SetProperty covers "
+                "the video transform only, so 'Volume'/'Gain' return False and "
+                "'Pan' moves the video transform, not the audio pan. Work "
+                "around it by baking the gain into a rendered copy of the "
+                "source (ffmpeg volume=NdB) and importing that, or (Resolve "
+                "20.2.2+) by saving a Fairlight preset in the UI and applying "
+                "it with project_settings apply_fairlight_preset."
+            )
     except Exception as e:
         return f"Error setting timeline item audio properties: {str(e)}"
 

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "4.9.0"
+VERSION = "4.9.1"
 
 import base64
 import os
@@ -803,10 +803,13 @@ edits audio files with no Resolve open. Plan/measure offline, apply live.
 - Offline `audio`: split (silence/TC/intervals) / trim / convert (needs ffmpeg on
   PATH — GPL, not bundled). Align/loudness-measure not yet vendored.
 
-Timeline audio SetProperty (e.g. Volume) can return false for some item types;
-the public API exposes no Fairlight automation curves — use fairlight for bus
-structure only. The offline audio ops write NEW files to scratch, never over
-source (AGENTS.md).
+Timeline audio SetProperty for level/pan/EQ does not work — 'Volume'/'Gain'
+return false and 'Pan' writes the video transform, not the audio pan; the
+public API exposes no Fairlight faders or automation curves. safe_set_audio_properties
+and timeline_item set_audio return a `known_limitation` block pointing at the
+fix: bake the gain into a rendered copy of the source, or apply a saved
+Fairlight preset. Use fairlight for bus structure only. The offline audio ops
+write NEW files to scratch, never over source (AGENTS.md).
 
 Depth: docs/kernels/audio-fairlight-kernel.md."""
 
@@ -8807,7 +8810,7 @@ def _audio_capabilities():
         "partially_supported": {
             "voice_isolation": "Track/item voice isolation depends on Resolve version, license, page state, and audio content.",
             "transcription_subtitles": "Transcription and subtitle generation can be asynchronous and may require installed AI components.",
-            "audio_property_writes": "Some item types expose audio properties as read-only or reject writes despite returning readable values.",
+            "audio_property_writes": "Level/pan/EQ writes are not honoured: SetProperty('Volume'/'Gain') returns False and 'Pan' writes the video transform. AudioSyncOffset writes do work. safe_set_audio_properties returns a known_limitation block with the bake / Fairlight-preset workaround.",
             "auto_sync": "AutoSyncAudio depends on media content, channel layout, and selected sync settings.",
         },
         "unsupported": {
@@ -8899,6 +8902,61 @@ def _probe_audio_item(tl, p: Dict[str, Any]):
     return _timeline_item_audio_snapshot(item)
 
 
+_AUDIO_LEVEL_KEYS = {"Volume", "Level", "Gain", "AudioVolume", "Pan", "EQEnable", "EQEnabled"}
+
+
+def _audio_write_limitation(written: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Guidance for an audio level/pan/EQ write that Resolve will not honour.
+
+    `written` maps each requested key to whether SetProperty returned True.
+    `SetProperty` on a TimelineItem covers the *video* transform only.
+    'Volume'/'Level'/'Gain' returned False when measured live on 21.0.0, and
+    'Pan' is the video-transform key — it returns True while the audio pan
+    stays put. A caller who sees `write: false` (or a Pan write that
+    "succeeds" and changes nothing) has hit a missing feature, not a bad
+    value, and the way around it is a different task: bake the gain into the
+    media, or drive Fairlight. Level/EQ keys are flagged only when the write
+    failed, so a build that honours them is not contradicted; Pan is always
+    flagged, because its success is the misleading case.
+    """
+    hit = sorted({
+        k for k, ok in written.items()
+        if k in _AUDIO_LEVEL_KEYS and (k == "Pan" or not ok)
+    })
+    if not hit:
+        return None
+    entry = next(iter(lookup_api_truth("Fairlight audio levels")), None)
+    out = {
+        "keys": hit,
+        "reason": "no_api_write_path",
+        "explanation": (
+            "Resolve's scripting API cannot set audio clip or track level, pan, "
+            "EQ, or automation. SetProperty writes the video transform only: "
+            "'Volume'/'Level'/'Gain' return False, and 'Pan' is the video "
+            "transform key so it returns True while the audio pan is unchanged."
+        ),
+        "workarounds": [
+            "Bake the level into a rendered copy of the source (ffmpeg "
+            "volume=NdB, plus afade / atrim for fades and trims) and import "
+            "that — the level is then part of the file.",
+            "For a repeatable whole mix (Resolve 20.2.2+; the preset methods "
+            "do not exist on 19.x), save it once as a Fairlight preset in "
+            "the Resolve UI, then apply it per timeline with "
+            "project_settings apply_fairlight_preset "
+            "(names from resolve_control get_fairlight_presets).",
+            "Set individual faders / pan / EQ on the Fairlight page by hand.",
+        ],
+        "ledger_verified_on": _API_TRUTH_VERIFIED_ON,
+    }
+    if entry:
+        out["ledger"] = {
+            "symbol": entry.get("symbol"),
+            "reality": entry.get("reality"),
+            "recommended": entry.get("recommended"),
+        }
+    return out
+
+
 def _safe_set_audio_properties(tl, p: Dict[str, Any]):
     item, err = _audio_item_from_params(tl, p)
     if err:
@@ -8938,7 +8996,18 @@ def _safe_set_audio_properties(tl, p: Dict[str, Any]):
                 row["restore"] = False
                 row["restore_error"] = str(exc)
         results[key] = row
-    return {"success": all(row.get("write") for row in results.values()), "results": results}
+    success = all(row.get("write") for row in results.values())
+    out = {"success": success, "results": results}
+    # 'Volume' never writes and 'Pan' moves the video transform, not the audio
+    # pan — so a bare {"write": false} (or a Pan that "succeeds" inertly) leaves
+    # the caller guessing. Attach the ledger entry and the bake / preset route
+    # whenever one of those keys was in play.
+    limitation = _audio_write_limitation(
+        {k: row.get("write") for k, row in results.items()}
+    )
+    if limitation:
+        out["known_limitation"] = limitation
+    return out
 
 
 def _voice_isolation_capabilities(tl, p: Dict[str, Any]):
@@ -26012,7 +26081,10 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       audio_capabilities() -> {supported, partially_supported, unsupported}
       probe_audio_item(track_type?, track_index?, item_index?) -> {summary, audio_properties, source_audio_mapping}
       probe_audio_track(track_index?) -> {track_count, enabled, locked, sub_type, voice_isolation}
-      safe_set_audio_properties(properties, restore?, dry_run?, track_type?, track_index?, item_index?) -> {success, results}
+      safe_set_audio_properties(properties, restore?, dry_run?, track_type?, track_index?, item_index?) -> {success, results, known_limitation?}
+        — Volume/Pan/EQ writes are not honoured by Resolve's API; a request for
+          any of them returns `known_limitation` with the bake / Fairlight-preset
+          workaround. AudioSyncOffset writes do work.
       audio_mix_capability_report(...) -> {capabilities, mix_recommendations}
       voice_isolation_capabilities(track_index?, track_type?, item_index?) -> {timeline_track, item}
       audio_mapping_report(clip_ids?) -> {timeline_items, media_pool_items}
@@ -27091,7 +27163,10 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
       get_composite(...) -> {Opacity, CompositeMode}
       set_composite(Opacity?, CompositeMode?, ...) -> {success}
       get_audio(...) -> {Volume, Pan, AudioSyncOffset, ...}
-      set_audio(Volume?, Pan?, ...) -> {success}
+      set_audio(Volume?, Pan?, ...) -> {success, known_limitation?}
+        — Resolve ignores Volume/Pan/EQ writes on audio; those return a
+          `known_limitation` block (bake gain into the media, or apply a
+          Fairlight preset). AudioSyncOffset / AudioSyncOffsetIsManual do work.
       get_keyframes(property, ...) -> {property, count, keyframes}
       add_keyframe(property, frame, value, ...) -> {success}
       modify_keyframe(property, frame, new_value?, new_frame?, ...) -> {success}
@@ -27326,7 +27401,15 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
         for k, v in p.items():
             if k in valid:
                 results[k] = bool(item.SetProperty(k, v))
-        return _ok(**results) if results else _err(f"Specify one or more of: {', '.join(sorted(valid))}")
+        if not results:
+            return _err(f"Specify one or more of: {', '.join(sorted(valid))}")
+        out = _ok(**results)
+        # Volume/Pan writes go nowhere on audio (see _audio_write_limitation);
+        # AudioSyncOffset does work, so only flag when a level/pan key was asked.
+        limitation = _audio_write_limitation(results)
+        if limitation:
+            out["known_limitation"] = limitation
+        return out
 
     # ── Keyframes ──
     elif action == "get_keyframes":