davinci-resolve-mcp 2.95.0 → 2.95.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +44 -0
- package/README.md +1 -1
- package/README.zh-CN.md +2 -2
- package/docs/reference/api-limitations.md +1 -1
- package/install.py +1 -1
- package/package.json +1 -1
- package/resolve-advanced/vendor/drp-format/README.md +28 -4
- package/src/granular/common.py +1 -1
- package/src/server.py +1 -1
- package/src/utils/api_truth.py +17 -3
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,50 @@
|
|
|
2
2
|
|
|
3
3
|
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.
|
|
4
4
|
|
|
5
|
+
## What's New in v2.95.1
|
|
6
|
+
|
|
7
|
+
Withdraws a recommendation this project shipped two releases ago. **`drp
|
|
8
|
+
place_fusion_title` produces a title Resolve never renders**, and v2.93.2/v2.93.3
|
|
9
|
+
told callers to use it.
|
|
10
|
+
|
|
11
|
+
### Fixed — the offline title is inert
|
|
12
|
+
|
|
13
|
+
Measured on Studio 21.0.4.5. The placed clip is structurally perfect: right
|
|
14
|
+
track, right frame, right duration, `PrettyType` = `Fusion Title`, and the text
|
|
15
|
+
genuinely is written into the `CompositionBA` — it decodes back. But Resolve
|
|
16
|
+
never instantiates the comp:
|
|
17
|
+
|
|
18
|
+
| | offline-placed | live-inserted |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `GetFusionCompCount()` | 1 | 1 |
|
|
21
|
+
| `GetToolList()` | **`[]`** | `['Template','MediaOut1']` |
|
|
22
|
+
| Inspector Title tab | **blank** | shows `Text+` |
|
|
23
|
+
| Viewer | **black** | renders the text |
|
|
24
|
+
|
|
25
|
+
Reproduced four ways — alone, inside an edit chain, onto a bundled-template base
|
|
26
|
+
project, and onto a genuine 21.0.4.5 Resolve export. Ruled out: template
|
|
27
|
+
staleness (the bundled clip element is structurally identical to a real one, same
|
|
28
|
+
tags, size differing only by text length) and DbId rewriting (the comp blobs hold
|
|
29
|
+
no DbId references). Root cause open.
|
|
30
|
+
|
|
31
|
+
It passes every structural readback while being invisible on screen — the exact
|
|
32
|
+
silent-lie shape the `api_truth` ledger exists to catch. The **nested-timeline
|
|
33
|
+
route is unaffected** and remains the working answer.
|
|
34
|
+
|
|
35
|
+
### Narrowed — it is the Fusion-comp path, not clone-a-template
|
|
36
|
+
|
|
37
|
+
`place_generator`, built the same way, works: an imported Solid Color shows a
|
|
38
|
+
populated `Generator - Solid Color` Inspector with a live Color parameter. A
|
|
39
|
+
generator's parameters are a protobuf `EffectFiltersBA`, which Resolve reads; a
|
|
40
|
+
title's are a `CompositionBA` Fusion-comp blob, which it does not instantiate.
|
|
41
|
+
|
|
42
|
+
### Changed — "mapped" no longer implies "Resolve honours it"
|
|
43
|
+
|
|
44
|
+
The drp-format README's honest-scope section conflated file-level fidelity with
|
|
45
|
+
live behaviour. A blob that survives a write/read cycle has been *encoded*
|
|
46
|
+
correctly; only a live import proves it is *instantiated*. The section now says
|
|
47
|
+
so, and the Fusion-title row carries the warning.
|
|
48
|
+
|
|
5
49
|
## What's New in v2.95.0
|
|
6
50
|
|
|
7
51
|
Compound clips can now be walked into and edited offline — the one capability
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
English | [简体中文](README.zh-CN.md)
|
|
4
4
|
|
|
5
|
-
[](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
|
|
6
6
|
[](https://www.npmjs.com/package/davinci-resolve-mcp)
|
|
7
7
|
[](docs/reference/api-coverage.md)
|
|
8
8
|
[-blue.svg)](#server-modes)
|
package/README.zh-CN.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md) | 简体中文
|
|
4
4
|
|
|
5
|
-
[](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
|
|
6
6
|
[](https://www.npmjs.com/package/davinci-resolve-mcp)
|
|
7
7
|
[](docs/reference/api-coverage.md)
|
|
8
8
|
[-blue.svg)](#服务器模式)
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
[](https://www.python.org/downloads/)
|
|
13
13
|
[](https://opensource.org/licenses/MIT)
|
|
14
14
|
|
|
15
|
-
> 本翻译对应 v2.95.
|
|
15
|
+
> 本翻译对应 v2.95.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
|
|
16
16
|
|
|
17
17
|
一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
|
|
18
18
|
|
|
@@ -67,7 +67,7 @@ equivalent, blocking full automation.
|
|
|
67
67
|
|
|
68
68
|
- **Object:** `Timeline`
|
|
69
69
|
- **Behavior:** There is no API to read or set the Source/Auto Track Selector (the Edit-page patch panel that picks the destination track). InsertTitleIntoTimeline, InsertFusionTitleIntoTimeline, InsertGeneratorIntoTimeline, InsertFusionGeneratorIntoTimeline, InsertOFXGeneratorIntoTimeline and InsertFusionCompositionIntoTimeline take no trackIndex and always drop the clip on the selector's current target (V1 in practice). Locking lower video tracks does NOT redirect the insert — verified live on 21.0.0: locking V1 makes the insert FAIL rather than land on V2. Titles/generators also can't be moved afterward (no MediaPoolItem, so AppendToTimeline clipInfo and MoveClips don't apply). RE-MEASURED on Studio 21.0.4.5 (2026-08-12, version read live), one fresh 3-video-track timeline per arm so no insert could fail on a collision: nothing locked -> lands V1; V1 locked via SetTrackLock -> returns None; V1 locked by CLICKING THE PADLOCK IN THE UI -> returns None, IDENTICAL to the API lock. That kills the recurring theory that the GUI lock advances the selector where the API lock does not — it does not, and a revision of resolve-advanced/vendor/drp-format/README.md that claimed otherwise as 'verified live' has been withdrawn as false. WHAT DOES WORK, and it is the whole mechanism: dragging the SOURCE PATCH badge onto V2 in the Edit-page patch panel sends the next insert to V2 (measured, same rig, nothing locked). The destination is the patch panel, never the lock state. In the track header the per-track badge column is the auto-track-selector toggle, while the source patch badge appears only on the patched track and dragging THAT is what re-targets. So THE SELECTOR itself is reachable only by GUI automation, and exposing read/write on the patch panel is a smaller, better-defined API request than adding trackIndex to all six Insert*IntoTimeline methods. Do not read that as 'a title cannot be placed on a chosen track from a script' — it can, without touching the selector at all, by nesting it (see the recommendation). The gap is in these six methods and in selector access, not in the outcome.
|
|
70
|
-
- **Workaround / current handling:** USE THE NESTED-TIMELINE ROUTE — the insert method is a dead end but the goal is not, and this is entirely public API. Measured end to end on Studio 21.0.4.5 (2026-08-12): put the title on its OWN timeline (CreateEmptyTimeline + InsertFusionTitleIntoTimeline; it lands on V1 there and that does not matter), then place THAT timeline's media pool item — Timeline.GetMediaPoolItem(), clip property Type='Timeline' — with AppendToTimeline's clipInfo trackIndex/recordFrame. It lands on the requested track at the requested frame, exactly. The text stays settable afterwards: placedItem.GetMediaPoolItem().GetTimeline() (Resolve 21.0.4+) opens the inner timeline, and the Text+ item there still reports GetFusionCompCount()==1, so GetFusionCompByIndex(1).FindTool('Template').SetInput('StyledText', ...) works and persists across processes. Duration is controllable the same way: duration = endFrame - startFrame, endFrame EXCLUSIVE (verified at 1, 119 and 120 frames). This composes — a PNG plus two titles each placed by trackIndex into one container timeline, and the container placed as a single clip, all elements individually reachable and editable through the nesting. TWO CONSTRAINTS: (a) every placed instance shares ONE media pool item, so a text edit propagates to all of them — use one source timeline per distinct card; (b) placements must not overlap on a track, or the append is silently rejected (see the overlapping-record entry). COMPOUND CLIPS ARE THE TRAP HERE: Timeline.CreateCompoundClip also gives a source-less title a MediaPoolItem and also places correctly, but it SEVERS the text — FusionCompCount drops 1->0 and GetTimeline() returns None for Type='Compound' while working correctly for Type='Timeline', so there is no route back to the Text+. Use a nested timeline, never a compound, when the text must stay editable. For clips that already have a MediaPoolItem, AppendToTimeline clipInfo 'trackIndex' was always the answer (exposed as media_pool append_to_timeline clip_infos). Do NOT reach for track locking in either form — it blocks the insert rather than re-targeting it. GUI automation of the patch panel works but is a last resort and is unverifiable from the API side; if used, read the landing track back with TimelineItem.GetTrackTypeAndIndex() and treat a wrong track as a failure.
|
|
70
|
+
- **Workaround / current handling:** USE THE NESTED-TIMELINE ROUTE — the insert method is a dead end but the goal is not, and this is entirely public API. Measured end to end on Studio 21.0.4.5 (2026-08-12): put the title on its OWN timeline (CreateEmptyTimeline + InsertFusionTitleIntoTimeline; it lands on V1 there and that does not matter), then place THAT timeline's media pool item — Timeline.GetMediaPoolItem(), clip property Type='Timeline' — with AppendToTimeline's clipInfo trackIndex/recordFrame. It lands on the requested track at the requested frame, exactly. The text stays settable afterwards: placedItem.GetMediaPoolItem().GetTimeline() (Resolve 21.0.4+) opens the inner timeline, and the Text+ item there still reports GetFusionCompCount()==1, so GetFusionCompByIndex(1).FindTool('Template').SetInput('StyledText', ...) works and persists across processes. Duration is controllable the same way: duration = endFrame - startFrame, endFrame EXCLUSIVE (verified at 1, 119 and 120 frames). This composes — a PNG plus two titles each placed by trackIndex into one container timeline, and the container placed as a single clip, all elements individually reachable and editable through the nesting. TWO CONSTRAINTS: (a) every placed instance shares ONE media pool item, so a text edit propagates to all of them — use one source timeline per distinct card; (b) placements must not overlap on a track, or the append is silently rejected (see the overlapping-record entry). COMPOUND CLIPS ARE THE TRAP HERE: Timeline.CreateCompoundClip also gives a source-less title a MediaPoolItem and also places correctly, but it SEVERS the text — FusionCompCount drops 1->0 and GetTimeline() returns None for Type='Compound' while working correctly for Type='Timeline', so there is no route back to the Text+. Use a nested timeline, never a compound, when the text must stay editable. For clips that already have a MediaPoolItem, AppendToTimeline clipInfo 'trackIndex' was always the answer (exposed as media_pool append_to_timeline clip_infos). Do NOT reach for track locking in either form — it blocks the insert rather than re-targeting it. GUI automation of the patch panel works but is a last resort and is unverifiable from the API side; if used, read the landing track back with TimelineItem.GetTrackTypeAndIndex() and treat a wrong track as a failure. DO NOT REACH FOR drp place_fusion_title HERE — an earlier revision of this entry recommended it and that recommendation is WITHDRAWN. Measured on Studio 21.0.4.5: it places a Fusion Title that is structurally perfect — right track, right frame, right duration, PrettyType 'Fusion Title', and the text really is written into the CompositionBA, which decodes back correctly — but Resolve never instantiates the comp. The imported item reports GetFusionCompCount()==1 while GetFusionCompByIndex(1).GetToolList() is EMPTY (a live-inserted Text+ returns ['Template','MediaOut1']), the Edit-page Inspector's Title tab is blank, and the viewer renders nothing. Reproduced four ways: placed alone, placed in an edit chain, onto a bundled-template base project, and onto a genuine 21.0.4.5 Resolve export. It therefore passes every structural readback while being invisible on screen — the exact silent-lie shape this ledger exists to catch. The nested-timeline route above is the one that actually works. See issue #74.
|
|
71
71
|
- **Reference:** [issue #74](https://github.com/samuelgursky/davinci-resolve-mcp/issues/74)
|
|
72
72
|
- **Tags:** missing-method, timeline, title, generator, track
|
|
73
73
|
|
package/install.py
CHANGED
|
@@ -36,7 +36,7 @@ from src.utils.update_check import (
|
|
|
36
36
|
|
|
37
37
|
# ─── Version ──────────────────────────────────────────────────────────────────
|
|
38
38
|
|
|
39
|
-
VERSION = "2.95.
|
|
39
|
+
VERSION = "2.95.1"
|
|
40
40
|
# Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
|
|
41
41
|
# Resolve's scripting bridge loads into newer interpreters on recent builds
|
|
42
42
|
# (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds
|
package/package.json
CHANGED
|
@@ -37,7 +37,7 @@ and `.../resolve-authoring-completion.md`.
|
|
|
37
37
|
**Place elements (track-targeted — the #74 bypass, offline)**
|
|
38
38
|
| Action | What it does |
|
|
39
39
|
|---|---|
|
|
40
|
-
| `place_fusion_title` | Text+ on a chosen track. Options: `text, font, style, size, vJustify, hJustify, color:{r,g,b}`, `trackIndex`, `startFrame`, `durationFrames` |
|
|
40
|
+
| `place_fusion_title` | ⚠️ **INERT on 21.0.4.5 — placed but not rendered, see below.** Text+ on a chosen track. Options: `text, font, style, size, vJustify, hJustify, color:{r,g,b}`, `trackIndex`, `startFrame`, `durationFrames` |
|
|
41
41
|
| `place_generator` | built-in generator (`generatorName`, e.g. "Solid Color") on a chosen track |
|
|
42
42
|
| `place_transition` | cross-dissolve at an abutting cut (`track`, `atFrame`, `durationFrames`) — clips need handle media |
|
|
43
43
|
|
|
@@ -117,16 +117,40 @@ Selector's current target (V1 in practice), which no API can read or set.
|
|
|
117
117
|
> locking. Treat it as such: it is not verifiable from the API side, since nothing in the
|
|
118
118
|
> scripting surface can confirm the selector landed where you dragged it.
|
|
119
119
|
|
|
120
|
-
|
|
121
|
-
|
|
120
|
+
> ⚠️ **`place_fusion_title` currently produces an INERT title — do not use it for this.**
|
|
121
|
+
> Measured on Studio 21.0.4.5: the placed clip is structurally perfect (right track, frame and
|
|
122
|
+
> duration, `PrettyType` = `Fusion Title`, and the text really is written into the
|
|
123
|
+
> `CompositionBA` — it decodes back), but **Resolve never instantiates the comp**. The imported
|
|
124
|
+
> item reports `GetFusionCompCount() == 1` while `GetFusionCompByIndex(1).GetToolList()` is
|
|
125
|
+
> **empty** (a live-inserted Text+ returns `['Template','MediaOut1']`), the Inspector's Title tab
|
|
126
|
+
> is blank, and the viewer renders nothing. Reproduced four ways: alone, in an edit chain, onto a
|
|
127
|
+
> bundled-template base, and onto a genuine 21.0.4.5 export. Ruled out so far — template staleness
|
|
128
|
+
> (the bundled clip element is structurally identical to a real one: same tags, size differing
|
|
129
|
+
> only by text length) and DbId rewriting (the comp blobs contain no DbId references). Root cause
|
|
130
|
+
> open. Use the live nested-timeline route until this is fixed.
|
|
131
|
+
>
|
|
132
|
+
> **The defect is specific to the Fusion-comp path, not to clone-a-template.** `place_generator`,
|
|
133
|
+
> built the same way, works: an imported Solid Color shows a populated `Generator - Solid Color`
|
|
134
|
+
> Inspector with a live Color parameter and renders on the timeline. The difference is where the
|
|
135
|
+
> parameters live — a generator's are a protobuf `EffectFiltersBA`, which Resolve reads happily,
|
|
136
|
+
> while a title's are a `CompositionBA` Fusion-comp blob, which it does not instantiate. That is
|
|
137
|
+
> the narrowest place to start looking.
|
|
122
138
|
|
|
123
139
|
---
|
|
124
140
|
|
|
125
141
|
## What's mapped (honest scope)
|
|
126
142
|
|
|
143
|
+
> **Read "mapped" as file-level fidelity, not as "Resolve honours it."** Those are different
|
|
144
|
+
> claims and this README conflated them. `place_fusion_title` round-trips byte-for-byte and its
|
|
145
|
+
> text decodes back correctly, yet Resolve builds no comp from it (see the ⚠️ above). A blob that
|
|
146
|
+
> survives a write/read cycle has been *encoded* correctly; only a live import proves it is
|
|
147
|
+
> *instantiated*. Everything below is the first claim. The second is only established where an
|
|
148
|
+
> entry says it was measured against a running Resolve build.
|
|
149
|
+
|
|
127
150
|
**Fully mapped (read + write, round-trips byte-for-byte):** project packaging; tracks
|
|
128
151
|
(`Sm2TiTrack`+Type+Sequence); clips; source in-points (`<In>`); Fusion titles
|
|
129
|
-
(text/font/style/size/justify/color
|
|
152
|
+
(text/font/style/size/justify/color — **encoded correctly but not instantiated by Resolve 21.0.4.5;
|
|
153
|
+
see the ⚠️ above**); generators; transitions; markers; grades (full DRX body);
|
|
130
154
|
media path + resolution + frame-count + fps. **Plus the full Media-Pool metadata layer:** the
|
|
131
155
|
keyed-dict format (`Geometry`/`Time`/`VideoMetadata`/`Proxy`/audio/small `FieldsBlob`) with typed
|
|
132
156
|
values (`keyed-dict.js`); audio config (`TracksBA`/`VirtualAudioTrackBA` → sample-rate/channels/codec
|
package/src/granular/common.py
CHANGED
|
@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
|
|
|
87
87
|
handlers=[logging.StreamHandler()],
|
|
88
88
|
)
|
|
89
89
|
|
|
90
|
-
VERSION = "2.95.
|
|
90
|
+
VERSION = "2.95.1"
|
|
91
91
|
logger = logging.getLogger("davinci-resolve-mcp")
|
|
92
92
|
logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
|
|
93
93
|
logger.info(f"Detected platform: {get_platform()}")
|
package/src/server.py
CHANGED
package/src/utils/api_truth.py
CHANGED
|
@@ -643,9 +643,23 @@ API_TRUTH: List[Dict[str, Any]] = [
|
|
|
643
643
|
"works but is a last resort and is unverifiable from the API "
|
|
644
644
|
"side; if used, read the landing track back with "
|
|
645
645
|
"TimelineItem.GetTrackTypeAndIndex() and treat a wrong track as "
|
|
646
|
-
"a failure.
|
|
647
|
-
"
|
|
648
|
-
"
|
|
646
|
+
"a failure. DO NOT REACH FOR drp place_fusion_title HERE — an "
|
|
647
|
+
"earlier revision of this entry recommended it and that "
|
|
648
|
+
"recommendation is WITHDRAWN. Measured on Studio 21.0.4.5: it "
|
|
649
|
+
"places a Fusion Title that is structurally perfect — right "
|
|
650
|
+
"track, right frame, right duration, PrettyType 'Fusion Title', "
|
|
651
|
+
"and the text really is written into the CompositionBA, which "
|
|
652
|
+
"decodes back correctly — but Resolve never instantiates the "
|
|
653
|
+
"comp. The imported item reports GetFusionCompCount()==1 while "
|
|
654
|
+
"GetFusionCompByIndex(1).GetToolList() is EMPTY (a live-inserted "
|
|
655
|
+
"Text+ returns ['Template','MediaOut1']), the Edit-page "
|
|
656
|
+
"Inspector's Title tab is blank, and the viewer renders nothing. "
|
|
657
|
+
"Reproduced four ways: placed alone, placed in an edit chain, "
|
|
658
|
+
"onto a bundled-template base project, and onto a genuine "
|
|
659
|
+
"21.0.4.5 Resolve export. It therefore passes every structural "
|
|
660
|
+
"readback while being invisible on screen — the exact silent-lie "
|
|
661
|
+
"shape this ledger exists to catch. The nested-timeline route "
|
|
662
|
+
"above is the one that actually works. See issue #74.",
|
|
649
663
|
"tags": ["missing-method", "timeline", "title", "generator", "track"],
|
|
650
664
|
"submit": "missing",
|
|
651
665
|
"issue": 74,
|