davinci-resolve-mcp 2.94.3 → 2.95.1

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 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.95.1
+
+Withdraws a recommendation this project shipped two releases ago. **`drp
+place_fusion_title` produces a title Resolve never renders**, and v2.93.2/v2.93.3
+told callers to use it.
+
+### Fixed — the offline title is inert
+
+Measured on Studio 21.0.4.5. The placed clip is structurally perfect: right
+track, right frame, right duration, `PrettyType` = `Fusion Title`, and the text
+genuinely is written into the `CompositionBA` — it decodes back. But Resolve
+never instantiates the comp:
+
+| | offline-placed | live-inserted |
+|---|---|---|
+| `GetFusionCompCount()` | 1 | 1 |
+| `GetToolList()` | **`[]`** | `['Template','MediaOut1']` |
+| Inspector Title tab | **blank** | shows `Text+` |
+| Viewer | **black** | renders the text |
+
+Reproduced four ways — alone, inside an edit chain, onto a bundled-template base
+project, and onto a genuine 21.0.4.5 Resolve export. Ruled out: template
+staleness (the bundled clip element is structurally identical to a real one, same
+tags, size differing only by text length) and DbId rewriting (the comp blobs hold
+no DbId references). Root cause open.
+
+It passes every structural readback while being invisible on screen — the exact
+silent-lie shape the `api_truth` ledger exists to catch. The **nested-timeline
+route is unaffected** and remains the working answer.
+
+### Narrowed — it is the Fusion-comp path, not clone-a-template
+
+`place_generator`, built the same way, works: an imported Solid Color shows a
+populated `Generator - Solid Color` Inspector with a live Color parameter. A
+generator's parameters are a protobuf `EffectFiltersBA`, which Resolve reads; a
+title's are a `CompositionBA` Fusion-comp blob, which it does not instantiate.
+
+### Changed — "mapped" no longer implies "Resolve honours it"
+
+The drp-format README's honest-scope section conflated file-level fidelity with
+live behaviour. A blob that survives a write/read cycle has been *encoded*
+correctly; only a live import proves it is *instantiated*. The section now says
+so, and the Fusion-title row carries the warning.
+
+## What's New in v2.95.0
+
+Compound clips can now be walked into and edited offline — the one capability
+where the offline tier beats the live scripting API outright.
+
+### Added — `drp` nested-sequence actions
+
+`list_nested`, `read_nested`, `read_nested_titles`, `set_nested_title_text`
+(`resolve-advanced/vendor/drp-format/compound-nav.js`). Enumerate every compound
+clip and nested timeline in a `.drp`, walk into either, and rewrite the title
+text inside.
+
+**A compound clip and a nested timeline are the same shape on disk.** Both appear
+in `MediaPool/Master/MpFolder.xml` as a media-pool element (`Sm2MpCompoundClip` /
+`Sm2MpTimelineClip`) carrying an inline `<Sequence><Sm2Sequence DbId="X">`, and
+the `SeqContainer/<uuid>.xml` whose tracks carry `<Sequence>X</Sequence>` holds
+the contents. The join is on that **Sm2Sequence DbId, not the container's own
+DbId** — which is referenced by nothing else in the package. One asymmetry: a
+compound's contents are rebased to `Start` 0 while a nested timeline's keep
+timeline-absolute TC.
+
+**Why this matters.** `MediaPoolItem.GetTimeline()` (21.0.4+) resolves through
+the timeline handle: it returns the inner Timeline for `Type='Timeline'` and
+**`None` for `Type='Compound'`**, and a compounded Text+ reports
+`GetFusionCompCount() == 0`. So compounding a title severs its text permanently
+as far as scripting is concerned — there is no API route back to it at any
+version. Offline, the distinction does not exist.
+
+Verified end to end on Studio 21.0.4.5: text rewritten offline inside a compound,
+imported into Resolve, re-exported by Resolve, and read back **from Resolve's own
+export** unchanged — so Resolve genuinely parses the write rather than tolerating
+it. Ten unit tests against a committed fixture exported from 21.0.4.5 holding a
+compound-of-media, a compound-of-Text+, and a nested timeline.
+
 ## What's New in v2.94.3
 
 A systematic sweep of catalogued API gaps against **Studio 21.0.4.5**, prompted

package/README.md

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

package/docs/reference/api-limitations.md

@@ -67,7 +67,7 @@ equivalent, blocking full automation.
 
 - **Object:** `Timeline`
 - **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.
-- **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. Offline, the advanced server's drp place_fusion_title places a title by track and frame directly. See issue #74.
+- **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.
 - **Reference:** [issue #74](https://github.com/samuelgursky/davinci-resolve-mcp/issues/74)
 - **Tags:** missing-method, timeline, title, generator, track
 

package/install.py

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

package/resolve-advanced/server/tools/drp.mjs

@@ -8,6 +8,7 @@
  * Edit: move_clip, delete_clip, trim_clip, trim_clip_head, split_clip, ripple_timeline
  * Media: relink_media, repoint_media
  * Grade: inject_grades, extract_node_graphs, diff
+ * Nested: list_nested, read_nested, read_nested_titles, set_nested_title_text (compounds + nested timelines)
  */
 
 import fs from 'node:fs/promises';
@@ -86,6 +87,26 @@ const S = {
   repoint_media: z.object({ ...io, mappings: z.array(z.object({}).passthrough()).describe('[{from,to,fromSpec,toSpec}] spec={width,height,frameCount,fps}') }),
   inject_grades: z.object({ ...io, grades: z.array(z.object({}).passthrough()).describe('[{ clipId|resolveId, drxContent }]') }),
   extract_node_graphs: z.object({ drpPath: io.drpPath, includeBodyHex: z.boolean().optional() }),
+  list_nested: z.object({
+    drpPath: io.drpPath,
+  }),
+  read_nested: z.object({
+    drpPath: io.drpPath,
+    name: z.string().describe('Compound or nested-timeline name as it appears in the media pool'),
+  }),
+  read_nested_titles: z.object({
+    drpPath: io.drpPath,
+    name: z.string().describe('Compound or nested-timeline name'),
+  }),
+  set_nested_title_text: z.object({
+    ...io,
+    name: z.string().describe('Compound or nested-timeline name'),
+    titleIndex: z.number().int().nonnegative().optional().describe('Which title inside, if several (default 0)'),
+    text: z.string().optional().describe('New on-screen text. No double quotes.'),
+    font: z.string().optional(),
+    style: z.string().optional(),
+    size: z.number().optional(),
+  }),
   extract_group_grades: z.object({
     drpPath: io.drpPath,
     groups: z.array(z.string()).optional().describe('Color group names; default = all groups in the project'),
@@ -108,7 +129,7 @@ async function writeOp(fnName, drpPath, opts, outputPath) {
 export const drpTool = {
   name: 'drp',
   description:
-    'DaVinci Resolve project (.drp) authoring + editing — offline, no Resolve required. Actions: create_empty_project, assemble_timeline, add_media_clip, place_fusion_title, place_generator, place_transition, move_clip, delete_clip, trim_clip, trim_clip_head, split_clip, ripple_timeline, relink_media, repoint_media, inject_grades, extract_node_graphs, extract_group_grades, diff, extract_lut_refs.',
+    'DaVinci Resolve project (.drp) authoring + editing — offline, no Resolve required. Actions: create_empty_project, assemble_timeline, add_media_clip, place_fusion_title, place_generator, place_transition, move_clip, delete_clip, trim_clip, trim_clip_head, split_clip, ripple_timeline, relink_media, repoint_media, inject_grades, extract_node_graphs, extract_group_grades, diff, extract_lut_refs, list_nested, read_nested, read_nested_titles, set_nested_title_text.',
   async handler({ action, args }) {
     const gen = drp();
 
@@ -221,6 +242,26 @@ export const drpTool = {
       }
       return { drpPath: p.drpPath, clipsWithGrade: graphs.length, totalClips: index.clipsById.size, graphs };
     }
+    // --- Nested sequences: compounds AND nested timelines. The scripting API
+    // cannot walk into a COMPOUND at all (MediaPoolItem.GetTimeline() is None
+    // for Type='Compound'), so these have no live counterpart.
+    if (action === 'list_nested') {
+      const p = S.list_nested.parse(args);
+      return { nested: await gen.listNestedSequences(p.drpPath) };
+    }
+    if (action === 'read_nested') {
+      const p = S.read_nested.parse(args);
+      return await gen.readNestedSequence(p.drpPath, { name: p.name });
+    }
+    if (action === 'read_nested_titles') {
+      const p = S.read_nested_titles.parse(args);
+      return { titles: await gen.readNestedTitles(p.drpPath, { name: p.name }) };
+    }
+    if (action === 'set_nested_title_text') {
+      const p = S.set_nested_title_text.parse(args);
+      const { drpPath, outputPath, ...opts } = p;
+      return writeOp('setNestedTitleText', drpPath, opts, outputPath);
+    }
     if (action === 'extract_group_grades') {
       const p = S.extract_group_grades.parse(args);
       const groups = await decodeGroupGrades(p.drpPath, { groups: p.groups, includePreClip: p.includePreClip });

package/resolve-advanced/vendor/drp-format/README.md

@@ -37,7 +37,7 @@ and `.../resolve-authoring-completion.md`.
 **Place elements (track-targeted — the #74 bypass, offline)**
 | Action | What it does |
 |---|---|
-| `place_fusion_title` | Text+ on a chosen track. Options: `text, font, style, size, vJustify, hJustify, color:{r,g,b}`, `trackIndex`, `startFrame`, `durationFrames` |
+| `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` |
 | `place_generator` | built-in generator (`generatorName`, e.g. "Solid Color") on a chosen track |
 | `place_transition` | cross-dissolve at an abutting cut (`track`, `atFrame`, `durationFrames`) — clips need handle media |
 
@@ -117,16 +117,40 @@ Selector's current target (V1 in practice), which no API can read or set.
 > locking. Treat it as such: it is not verifiable from the API side, since nothing in the
 > scripting surface can confirm the selector landed where you dragged it.
 
-For export-based workflows, `place_fusion_title` places a title on any track at an exact frame
-offline, with no selector involved.
+> ⚠️ **`place_fusion_title` currently produces an INERT title — do not use it for this.**
+> Measured on Studio 21.0.4.5: the placed clip is structurally perfect (right track, frame and
+> duration, `PrettyType` = `Fusion Title`, and the text really is written into the
+> `CompositionBA` — it decodes back), 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 Inspector's Title tab
+> is blank, and the viewer renders nothing. Reproduced four ways: alone, in an edit chain, onto a
+> bundled-template base, and onto a genuine 21.0.4.5 export. Ruled out so far — template staleness
+> (the bundled clip element is structurally identical to a real one: same tags, size differing
+> only by text length) and DbId rewriting (the comp blobs contain no DbId references). Root cause
+> open. Use the live nested-timeline route until this is fixed.
+>
+> **The defect is specific to the Fusion-comp path, not to clone-a-template.** `place_generator`,
+> built the same way, works: an imported Solid Color shows a populated `Generator - Solid Color`
+> Inspector with a live Color parameter and renders on the timeline. The difference is where the
+> parameters live — a generator's are a protobuf `EffectFiltersBA`, which Resolve reads happily,
+> while a title's are a `CompositionBA` Fusion-comp blob, which it does not instantiate. That is
+> the narrowest place to start looking.
 
 ---
 
 ## What's mapped (honest scope)
 
+> **Read "mapped" as file-level fidelity, not as "Resolve honours it."** Those are different
+> claims and this README conflated them. `place_fusion_title` round-trips byte-for-byte and its
+> text decodes back correctly, yet Resolve builds no comp from it (see the ⚠️ above). A blob that
+> survives a write/read cycle has been *encoded* correctly; only a live import proves it is
+> *instantiated*. Everything below is the first claim. The second is only established where an
+> entry says it was measured against a running Resolve build.
+
 **Fully mapped (read + write, round-trips byte-for-byte):** project packaging; tracks
 (`Sm2TiTrack`+Type+Sequence); clips; source in-points (`<In>`); Fusion titles
-(text/font/style/size/justify/color); generators; transitions; markers; grades (full DRX body);
+(text/font/style/size/justify/color — **encoded correctly but not instantiated by Resolve 21.0.4.5;
+see the ⚠️ above**); generators; transitions; markers; grades (full DRX body);
 media path + resolution + frame-count + fps. **Plus the full Media-Pool metadata layer:** the
 keyed-dict format (`Geometry`/`Time`/`VideoMetadata`/`Proxy`/audio/small `FieldsBlob`) with typed
 values (`keyed-dict.js`); audio config (`TracksBA`/`VirtualAudioTrackBA` → sample-rate/channels/codec
@@ -141,4 +165,21 @@ internal-state/cache `FieldsBlob`s (`classifyBlob` flags them; Node has no built
 protobuf blobs' *field names* (wire structure is decoded; names need Resolve's private `.proto`); the
 Fusion comp beyond the title inputs we edit.
 
+**Nested sequences — compounds AND nested timelines (`compound-nav.js`):** enumerate, walk
+into, and rewrite title text inside either. **A compound clip and a nested timeline are the same
+shape on disk:** both appear in `MediaPool/Master/MpFolder.xml` as a media-pool element
+(`Sm2MpCompoundClip` / `Sm2MpTimelineClip`) carrying an inline `<Sequence><Sm2Sequence DbId="X">`,
+and the `SeqContainer/<uuid>.xml` whose tracks carry `<Sequence>X</Sequence>` holds the contents.
+The join is on that **Sm2Sequence DbId, not the container's own DbId** — the container id is
+referenced by nothing else in the package. One asymmetry worth knowing: a compound's contents are
+rebased to `Start` 0, while a nested timeline's keep timeline-absolute TC.
+
+> This is the one place the offline tier beats the live API outright. `MediaPoolItem.GetTimeline()`
+> (21.0.4+) resolves through the timeline handle: it returns the inner Timeline for
+> `Type='Timeline'` and **`None` for `Type='Compound'`**, and a compounded Text+ reports
+> `GetFusionCompCount() == 0`. So compounding a title severs its text permanently as far as
+> scripting is concerned. Offline the distinction does not exist. Verified end to end on Studio
+> 21.0.4.5: text rewritten offline inside a compound, imported, re-exported by Resolve, and read
+> back **from Resolve's own export** unchanged.
+
 **Limit:** media authoring is h264-only (cross-codec needs a per-codec template).

package/resolve-advanced/vendor/drp-format/__tests__/compound-nav.test.js

@@ -0,0 +1,116 @@
+/**
+ * compound-nav — walking into compound clips and nested timelines.
+ *
+ * Fixture: compound-nav-r21.drp, exported from DaVinci Resolve Studio 21.0.4.5
+ * (DbPrjVer 17). It holds, deliberately, one of each interesting case:
+ *   CMP_MEDIA   compound wrapping a media clip
+ *   CMP_TITLE   compound wrapping a Text+ (text set to "INSIDE COMPOUND")
+ *   ZZ_CMP_TL   the outer timeline
+ *   ZZ_INNER_TL a plain nested timeline holding a Text+
+ *
+ * The compound cases are the point: the scripting API cannot reach into them at
+ * all. MediaPoolItem.GetTimeline() returns None for Type='Compound' (measured on
+ * 21.0.4.5) while working for Type='Timeline', and a compounded Text+ reports
+ * GetFusionCompCount()==0. On disk there is no such asymmetry.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const nav = require('../compound-nav');
+
+const FIXTURE = path.join(__dirname, 'fixtures', 'compound-nav-r21.drp');
+const hasFixture = fs.existsSync(FIXTURE);
+const maybe = hasFixture ? test : test.skip;
+
+maybe('listNestedSequences finds both compounds and both timelines', async () => {
+  const list = await nav.listNestedSequences(FIXTURE);
+  const byName = Object.fromEntries(list.map((e) => [e.name, e]));
+
+  assert.equal(list.length, 4);
+  assert.equal(byName.CMP_MEDIA.kind, 'compound');
+  assert.equal(byName.CMP_TITLE.kind, 'compound');
+  assert.equal(byName.ZZ_CMP_TL.kind, 'timeline');
+  assert.equal(byName.ZZ_INNER_TL.kind, 'timeline');
+});
+
+maybe('every nested sequence resolves to its own SeqContainer', async () => {
+  const list = await nav.listNestedSequences(FIXTURE);
+  for (const e of list) {
+    assert.ok(e.sequenceDbId, `${e.name} has no Sm2Sequence DbId`);
+    assert.ok(e.entry, `${e.name} did not resolve to a SeqContainer`);
+  }
+  // The join is one-to-one: no two media pool items share a container.
+  const entries = list.map((e) => e.entry);
+  assert.equal(new Set(entries).size, entries.length);
+});
+
+maybe('readNestedSequence returns the items inside a compound', async () => {
+  const media = await nav.readNestedSequence(FIXTURE, { name: 'CMP_MEDIA' });
+  assert.equal(media.kind, 'compound');
+  assert.equal(media.tracks.length, 1);
+  assert.equal(media.tracks[0].items.length, 1);
+  assert.equal(media.tracks[0].items[0].name, 'retime_src.mp4');
+  assert.equal(media.tracks[0].items[0].duration, 48);
+});
+
+maybe('compound contents are rebased to 0; a nested timeline keeps timeline TC', async () => {
+  const cmp = await nav.readNestedSequence(FIXTURE, { name: 'CMP_TITLE' });
+  const tl = await nav.readNestedSequence(FIXTURE, { name: 'ZZ_INNER_TL' });
+  assert.equal(cmp.tracks[0].items[0].start, 0);
+  assert.equal(tl.tracks[0].items[0].start, 86400);
+});
+
+maybe('readNestedTitles decodes text the scripting API cannot reach', async () => {
+  const titles = await nav.readNestedTitles(FIXTURE, { name: 'CMP_TITLE' });
+  assert.equal(titles.length, 1);
+  assert.equal(titles[0].text, 'INSIDE COMPOUND');
+  assert.equal(titles[0].font, 'Open Sans');
+});
+
+maybe('setNestedTitleText rewrites the text inside a compound', async () => {
+  const res = await nav.setNestedTitleText(FIXTURE, {
+    name: 'CMP_TITLE', text: 'REWRITTEN',
+  });
+  assert.equal(res.before.text, 'INSIDE COMPOUND');
+  assert.equal(res.after.text, 'REWRITTEN');
+
+  // Re-read from the produced buffer, not from the in-memory result.
+  const again = await nav.readNestedTitles(res.buffer, { name: 'CMP_TITLE' });
+  assert.equal(again[0].text, 'REWRITTEN');
+  // Untouched inputs survive.
+  assert.equal(again[0].font, 'Open Sans');
+  assert.equal(again[0].size, 0.09);
+});
+
+maybe('setNestedTitleText leaves the other compound alone', async () => {
+  const res = await nav.setNestedTitleText(FIXTURE, {
+    name: 'CMP_TITLE', text: 'ONLY THIS ONE',
+  });
+  const other = await nav.readNestedSequence(res.buffer, { name: 'CMP_MEDIA' });
+  assert.equal(other.tracks[0].items[0].name, 'retime_src.mp4');
+  assert.equal(other.tracks[0].items[0].duration, 48);
+});
+
+maybe('unknown name throws rather than silently doing nothing', async () => {
+  await assert.rejects(
+    () => nav.readNestedSequence(FIXTURE, { name: 'NOPE' }),
+    /no compound or timeline named/,
+  );
+});
+
+maybe('a double quote in the text is refused (it would break the Lua blob)', async () => {
+  await assert.rejects(
+    () => nav.setNestedTitleText(FIXTURE, { name: 'CMP_TITLE', text: 'say "hi"' }),
+    /must not contain double quotes/,
+  );
+});
+
+maybe('titleIndex out of range names the count it saw', async () => {
+  await assert.rejects(
+    () => nav.setNestedTitleText(FIXTURE, { name: 'CMP_TITLE', text: 'x', titleIndex: 7 }),
+    /has 1 title\(s\); no index 7/,
+  );
+});

package/resolve-advanced/vendor/drp-format/compound-nav.js

@@ -0,0 +1,232 @@
+/**
+ * compound-nav — walk INTO compound clips and nested timelines in a .drp.
+ *
+ * A compound clip and a nested timeline are the same shape on disk: a sequence
+ * inside a sequence. Both appear in `MediaPool/Master/MpFolder.xml` as a media
+ * pool element (`Sm2MpCompoundClip` / `Sm2MpTimelineClip`) carrying an inline
+ * `<Sequence><Sm2Sequence DbId="X">`, and the `SeqContainer/<uuid>.xml` whose
+ * tracks reference `<Sequence>X</Sequence>` holds the contents. The container's
+ * own filename/DbId is referenced by NOTHING else in the package — the join is
+ * on the Sm2Sequence DbId, not the container id.
+ *
+ * This matters because the SCRIPTING API cannot do it. MediaPoolItem.GetTimeline()
+ * (Resolve 21.0.4+) resolves through the timeline handle: it returns the inner
+ * Timeline for a `Type='Timeline'` item and None for a `Type='Compound'` one.
+ * Compounding a Text+ therefore severs its text permanently as far as the API is
+ * concerned — FusionCompCount drops 1 -> 0 and nothing reaches the tools inside.
+ * Offline, the distinction does not exist: both are just a nested <Sequence>.
+ *
+ * Verified against a Resolve Studio 21.0.4.5 export (DbPrjVer 17) containing a
+ * compound-of-media, a compound-of-Text+, and a nested timeline.
+ *
+ * @module drp-format/compound-nav
+ */
+
+const { loadDrpZip, splitTrackElements, splitClipElements, getItemsInner } = require('./seq-surgery');
+
+const MP_FOLDER = 'MediaPool/Master/MpFolder.xml';
+
+const KINDS = {
+  Sm2MpCompoundClip: 'compound',
+  Sm2MpTimelineClip: 'timeline',
+};
+
+const tagValue = (xml, tag) => {
+  const m = xml.match(new RegExp(`<${tag}>([^<]*)</${tag}>`));
+  return m ? m[1] : null;
+};
+
+/**
+ * The Sm2Sequence DbId a media pool element points at.
+ * Read from the element's own <Sequence> child, NOT from any later sibling.
+ */
+function sequenceDbIdOf(elementXml) {
+  const m = elementXml.match(/<Sequence>\s*<Sm2Sequence\s+DbId="([^"]+)"/);
+  return m ? m[1] : null;
+}
+
+/** Every SeqContainer entry, mapped by the Sm2Sequence DbId its tracks carry. */
+async function containersBySequenceId(zip) {
+  const out = new Map();
+  for (const name of Object.keys(zip.files)) {
+    if (!/^SeqContainer\/[^/]+\.xml$/.test(name)) continue;
+    const xml = await zip.file(name).async('string');
+    const seq = tagValue(xml, 'Sequence');
+    if (seq) out.set(seq, { entry: name, xml });
+  }
+  return out;
+}
+
+/**
+ * List every nested sequence in the package — compounds AND timelines.
+ *
+ * @param {Buffer|string} drpInput
+ * @returns {Promise<Array<{kind:'compound'|'timeline', name:string,
+ *   sequenceDbId:string, entry:string|null, mediaPoolItemId:string|null,
+ *   videoTracks:number, itemCount:number}>>}
+ */
+async function listNestedSequences(drpInput) {
+  const zip = await loadDrpZip(drpInput);
+  const mp = await zip.file(MP_FOLDER).async('string');
+  const bySeq = await containersBySequenceId(zip);
+
+  const results = [];
+  for (const [tag, kind] of Object.entries(KINDS)) {
+    const re = new RegExp(`<${tag}\\b[\\s\\S]*?</${tag}>`, 'g');
+    for (const m of mp.matchAll(re)) {
+      const el = m[0];
+      const sequenceDbId = sequenceDbIdOf(el);
+      const found = sequenceDbId ? bySeq.get(sequenceDbId) : null;
+      let videoTracks = 0;
+      let itemCount = 0;
+      if (found) {
+        const vec = found.xml.match(/<VideoTrackVec>([\s\S]*?)<\/VideoTrackVec>/);
+        const tracks = vec ? splitTrackElements(vec[1]) : [];
+        videoTracks = tracks.length;
+        itemCount = tracks.reduce(
+          (n, t) => n + splitClipElements(getItemsInner(t) || '').length, 0);
+      }
+      results.push({
+        kind,
+        name: tagValue(el, 'Name'),
+        sequenceDbId,
+        entry: found ? found.entry : null,
+        mediaPoolItemId: tagValue(el, 'UniqueMediaPoolItemId'),
+        videoTracks,
+        itemCount,
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * Read the contents of one nested sequence by media pool name.
+ *
+ * @param {Buffer|string} drpInput
+ * @param {object} opts
+ * @param {string} opts.name - the compound / timeline name in the media pool.
+ * @returns {Promise<{kind:string, name:string, entry:string,
+ *   tracks:Array<{index:number, items:Array<{type:string, name:string,
+ *   start:number|null, duration:number|null, dbId:string|null}>}>}>}
+ */
+async function readNestedSequence(drpInput, opts = {}) {
+  const { name } = opts;
+  if (!name) throw new TypeError('readNestedSequence: name is required');
+  const zip = await loadDrpZip(drpInput);
+  const list = await listNestedSequences(drpInput);
+  const hit = list.find((e) => e.name === name);
+  if (!hit) throw new Error(`readNestedSequence: no compound or timeline named ${JSON.stringify(name)}`);
+  if (!hit.entry) throw new Error(`readNestedSequence: ${name} has no SeqContainer (sequence ${hit.sequenceDbId})`);
+
+  const xml = await zip.file(hit.entry).async('string');
+  const vec = xml.match(/<VideoTrackVec>([\s\S]*?)<\/VideoTrackVec>/);
+  const tracks = (vec ? splitTrackElements(vec[1]) : []).map((t, i) => ({
+    index: i + 1,
+    items: splitClipElements(getItemsInner(t) || '').map((c) => {
+      const typeMatch = c.match(/<(Sm2Ti[A-Za-z]+)\b/);
+      const idMatch = c.match(/<Sm2Ti[A-Za-z]+\s+DbId="([^"]+)"/);
+      const num = (tag) => {
+        const v = tagValue(c, tag);
+        return v == null ? null : parseInt(v, 10);
+      };
+      return {
+        type: typeMatch ? typeMatch[1] : 'unknown',
+        name: tagValue(c, 'Name'),
+        start: num('Start'),
+        duration: num('Duration'),
+        dbId: idMatch ? idMatch[1] : null,
+      };
+    }),
+  }));
+  return { kind: hit.kind, name: hit.name, entry: hit.entry, tracks };
+}
+
+/** Locate the nested sequence's container entry + xml, or throw. */
+async function resolveEntry(zip, drpInput, name) {
+  const list = await listNestedSequences(drpInput);
+  const hit = list.find((e) => e.name === name);
+  if (!hit) throw new Error(`no compound or timeline named ${JSON.stringify(name)}`);
+  if (!hit.entry) throw new Error(`${name} has no SeqContainer (sequence ${hit.sequenceDbId})`);
+  return { hit, xml: await zip.file(hit.entry).async('string') };
+}
+
+const COMPOSITION_BA = /<CompositionBA>([^<]*)<\/CompositionBA>/g;
+
+/**
+ * Read the title inputs of every Fusion title inside a nested sequence.
+ *
+ * This is the operation the scripting API cannot perform on a compound at all:
+ * MediaPoolItem.GetTimeline() is None for Type='Compound', and the compounded
+ * item reports GetFusionCompCount()==0, so there is no route to the text.
+ *
+ * @param {Buffer|string} drpInput
+ * @param {object} opts
+ * @param {string} opts.name
+ * @returns {Promise<Array<{index:number, text:string, font:string, style:string,
+ *   size:number, vJustify:number, hJustify:number}>>}
+ */
+async function readNestedTitles(drpInput, opts = {}) {
+  const { name } = opts;
+  if (!name) throw new TypeError('readNestedTitles: name is required');
+  const zip = await loadDrpZip(drpInput);
+  const { xml } = await resolveEntry(zip, drpInput, name);
+  const { decodeTitleInputs } = require('./composition-text');
+  const out = [];
+  let i = 0;
+  for (const m of xml.matchAll(COMPOSITION_BA)) {
+    out.push({ index: i++, ...decodeTitleInputs(m[1]) });
+  }
+  return out;
+}
+
+/**
+ * Rewrite the text (and optionally font/style/size/justification) of a Fusion
+ * title INSIDE a compound or nested timeline.
+ *
+ * @param {Buffer|string} drpInput
+ * @param {object} opts
+ * @param {string} opts.name              - compound / timeline name.
+ * @param {number} [opts.titleIndex=0]    - which title inside, if several.
+ * @param {string} [opts.text]            - new on-screen text (no double quotes).
+ * @param {string} [opts.font] @param {string} [opts.style] @param {number} [opts.size]
+ * @returns {Promise<{buffer:Buffer, entry:string, name:string, titleIndex:number,
+ *   before:object, after:object}>}
+ */
+async function setNestedTitleText(drpInput, opts = {}) {
+  const { name, titleIndex = 0, ...inputs } = opts;
+  if (!name) throw new TypeError('setNestedTitleText: name is required');
+  if (typeof inputs.text === 'string' && inputs.text.includes('"')) {
+    throw new Error('setNestedTitleText: text must not contain double quotes');
+  }
+  const zip = await loadDrpZip(drpInput);
+  const { hit, xml } = await resolveEntry(zip, drpInput, name);
+  const { decodeTitleInputs, setTitleInputs } = require('./composition-text');
+
+  const blobs = [...xml.matchAll(COMPOSITION_BA)];
+  if (!blobs[titleIndex]) {
+    throw new Error(`setNestedTitleText: ${name} has ${blobs.length} title(s); no index ${titleIndex}`);
+  }
+  const target = blobs[titleIndex];
+  const before = decodeTitleInputs(target[1]);
+  const rewritten = setTitleInputs(target[1], inputs);
+  const after = decodeTitleInputs(rewritten);
+
+  // Splice by offset — the same hex can legitimately appear more than once.
+  const start = target.index;
+  const patched = xml.slice(0, start)
+    + `<CompositionBA>${rewritten}</CompositionBA>`
+    + xml.slice(start + target[0].length);
+
+  zip.file(hit.entry, patched);
+  const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  return { buffer, entry: hit.entry, name, titleIndex, before, after };
+}
+
+module.exports = {
+  listNestedSequences,
+  readNestedSequence,
+  readNestedTitles,
+  setNestedTitleText,
+  sequenceDbIdOf,
+};

package/resolve-advanced/vendor/drp-format/index.js

@@ -142,6 +142,13 @@ module.exports = {
   trimClip: require('./splice-clips').trimClip,
   trimClipHead: require('./splice-clips').trimClipHead,
   splitClip: require('./splice-clips').splitClip,
+  // Nested sequences — compounds AND nested timelines (compound-nav.js). The
+  // scripting API cannot walk into a compound at all: MediaPoolItem.GetTimeline()
+  // returns None for Type='Compound' while working for Type='Timeline'.
+  listNestedSequences: require('./compound-nav').listNestedSequences,
+  readNestedSequence: require('./compound-nav').readNestedSequence,
+  readNestedTitles: require('./compound-nav').readNestedTitles,
+  setNestedTitleText: require('./compound-nav').setNestedTitleText,
   rippleTimeline: require('./splice-clips').rippleTimeline,
 
   // Create a fresh, importable Resolve project (one empty timeline) from a bundled template.

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.94.3"
+VERSION = "2.95.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/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.94.3"
+VERSION = "2.95.1"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -643,9 +643,23 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "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. Offline, the advanced server's drp "
-                       "place_fusion_title places a title by track and frame directly. "
-                       "See issue #74.",
+                       "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.",
         "tags": ["missing-method", "timeline", "title", "generator", "track"],
         "submit": "missing",
         "issue": 74,