davinci-resolve-mcp 2.94.2 → 2.95.0

package/CHANGELOG.md

@@ -2,6 +2,90 @@
 
 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.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
+by an external report. Two ledger entries were wrong and are corrected; a new
+harness proves the routes that DO work.
+
+### Fixed — transitions are not invisible to scripting
+
+- **`Transition create / copy / clone` claimed transitions applied in the UI are
+  "invisible to and unmodifiable by scripts". Both halves were wrong.** A
+  12-frame Cross Dissolve applied through the Edit-page right-click menu
+  enumerates in `GetItemListInTrack` as `GetName() == 'Cross Dissolve'`,
+  `GetStart() == 86426`, `GetDuration() == 12` — centered on a cut at 86432 —
+  with a stable `GetUniqueId()`. One authored offline into a `.drp` and imported
+  reads identically, so the creating route is irrelevant. It is also removable:
+  `DeleteClips([transition], False)` returns True and leaves both adjacent clips
+  untouched. **The discriminator** is `GetProperty()`: empty on a transition, 26
+  transform keys on a clip. Automated QC of existing transitions is therefore
+  possible. Genuinely missing: creation, cloning, and any type/alignment detail —
+  the kind is knowable only from the name string.
+
+### Fixed — CreateProject is not an "Untitled project" problem
+
+- **`CreateProject` returned None with a NAMED project current and no modal on
+  screen** (screenshot-confirmed), while `OpenPage('edit')` succeeded in the same
+  session — so the connection was healthy and the documented modal is not the
+  only mechanism. Loading any clean project unblocked it on the next call. The
+  entry's recommended workaround was `CloseProject`, which **discards unsaved
+  changes** — acceptable for a throwaway Untitled project, destructive when the
+  current project is a named one belonging to another session. It now recommends
+  `LoadProject(clean project)` instead.
+
+### Added — `tests/live_workaround_verification.py`
+
+The sibling of the gap harness: where that one proves absence, this proves
+presence, performing each operation and reading the result back. Seven routes
+verified on 21.0.4.5 — nested-timeline title placement with a later text edit,
+ripple delete (with a non-ripple control showing the gap), the take selector as
+an in-place source swap, `GetSelectedClips`, and constant retime through both
+OTIO `LinearTimeWarp` and EDL `M2` (each a true 200%: 96 source frames over a
+48-frame record, alongside a 1.0 control). It also records the compound-clip trap
+as a deliberate `ROUTE FAILS`.
+
+### Changed — the gap harness covers 13 gaps, up from 8
+
+Added control-paired repros for the Source/Auto Track Selector (locking V1 blocks
+the insert rather than redirecting it, while a media-backed clip targets V2
+fine), transitions, native multicam creation, per-caption subtitle text, and
+per-clip audio channel mapping. **13/13 confirmed missing** on 21.0.4.5.
+
 ## What's New in v2.94.2
 
 Changelog repair. No code changed.

package/README.md

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

package/docs/reference/api-limitations.md

@@ -89,8 +89,8 @@ equivalent, blocking full automation.
 ### Transition create / copy / clone
 
 - **Object:** `Timeline / TimelineItem`
-- **Behavior:** The scripting API exposes no method to add, read, copy, or clone an edit transition (cross-dissolve, etc.). Transitions applied in the UI are invisible to and unmodifiable by scripts.
-- **Workaround / current handling:** Apply/duplicate transitions in the Resolve UI; no scripted equivalent exists.
+- **Behavior:** There is no method to ADD or CLONE an edit transition — no AddTransition/CreateTransition/AddVideoTransition on Timeline or TimelineItem (dir(), 21.0.4.5). CORRECTION, measured on Studio 21.0.4.5 (2026-08-12): this entry previously said transitions applied in the UI are 'invisible to and unmodifiable by scripts'. BOTH HALVES WERE WRONG and are withdrawn. A transition IS a first-class timeline item: a 12-frame Cross Dissolve applied through the Edit-page right-click menu enumerates in GetItemListInTrack('video', 1) as GetName()=='Cross Dissolve', GetStart()==86426, GetDuration()==12 — centered on a cut at 86432 — with a stable GetUniqueId() and a working GetTrackTypeAndIndex(). A transition authored offline into a .drp and imported reads IDENTICALLY, so the route that created it does not matter. It is also REMOVABLE: Timeline.DeleteClips([transition], False) returns True and deletes it, leaving both adjacent clips at their original starts and durations. THE DISCRIMINATOR between a transition item and a clip item is GetProperty(): a transition returns an EMPTY dict where a video clip returns 26 transform keys; it also has no MediaPoolItem and no Fusion comp. WHAT IS GENUINELY MISSING: creation, cloning, and any type/alignment/parameter detail — the transition's kind is knowable ONLY from its name string, and there is no way to read its alignment (centered/start/end) or edit its duration.
+- **Workaround / current handling:** Automated QC of existing transitions IS possible and is the main practical need — enumerate GetItemListInTrack, treat any item whose GetProperty() is empty and whose GetMediaPoolItem() is None as a transition, and read its name, start and duration. Removal is scriptable via Timeline.DeleteClips. To CREATE one, either apply it in the Resolve UI, or author it offline and import: the advanced server's drp place_transition writes a cross dissolve at an abutting cut ({track, atFrame, durationFrames}) and it round-trips into Resolve 21.0.4.5 reading back at the expected centered range.
 - **Tags:** missing-method, timeline, transition
 
 ### Cloud project enumeration / export / user management
@@ -367,11 +367,11 @@ values, or automation-hostile modal prompts.
 - **Workaround / current handling:** Treat a trailing ellipsis as truncation (see media_pool_item get_transcription's `truncated` flag).
 - **Tags:** transcription, truncation
 
-### ProjectManager.CreateProject (with a dirty Untitled project)
+### ProjectManager.CreateProject (blocked by the current project)
 
 - **Object:** `ProjectManager`
-- **Behavior:** Returns None and pops a modal 'Save Current Project' dialog when the current unsaved/Untitled project blocks the switch. SaveProject() on an Untitled project re-triggers the same modal.
-- **Workaround / current handling:** CloseProject(current) to discard the untitled project without a prompt, then CreateProject; restore with LoadProject afterward.
+- **Behavior:** Returns None and pops a modal 'Save Current Project' dialog when the current unsaved/Untitled project blocks the switch. SaveProject() on an Untitled project re-triggers the same modal. BROADER THAN 'UNTITLED', measured on Studio 21.0.4.5 (2026-08-12): with a NAMED project current (a conform project left open on the Deliver page), CreateProject returned None for a brand-new name and SaveProject returned False — with NO modal on screen, confirmed by screenshot, so the dialog is not the only mechanism. The connection was healthy throughout: OpenPage('edit') returned True in the same session, and moving to the Edit page did not help. Loading ANY clean project immediately unblocked it — CreateProject succeeded on the very next call. So the trigger is the current project, not the 'Untitled' name, and a bare False/None is the only signal.
+- **Workaround / current handling:** LoadProject(any clean project) first, then CreateProject; restore the caller's project afterward. PREFER THAT OVER CloseProject, which this entry used to recommend: CloseProject DISCARDS unsaved changes, which is fine for a throwaway Untitled project but destroys work when the current project is a named one belonging to someone else's session — and the failure is NOT limited to Untitled projects, so that is a live risk. Never assume a bare None here means the name is taken; check GetProjectListInCurrentFolder().
 - **Tags:** project, modal, silent-failure
 
 ### TimelineItem.GetSourceStartFrame

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.94.2"
+VERSION = "2.95.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.94.2",
+  "version": "2.95.0",
   "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

@@ -141,4 +141,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.2"
+VERSION = "2.95.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/server.py

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

package/src/utils/api_truth.py

@@ -525,14 +525,32 @@ API_TRUTH: List[Dict[str, Any]] = [
         "submit": "bug",
     },
     {
-        "symbol": "ProjectManager.CreateProject (with a dirty Untitled project)",
+        "symbol": "ProjectManager.CreateProject (blocked by the current project)",
         "object": "ProjectManager",
         "reality": "Returns None and pops a modal 'Save Current Project' dialog "
                    "when the current unsaved/Untitled project blocks the switch. "
-                   "SaveProject() on an Untitled project re-triggers the same modal.",
-        "recommended": "CloseProject(current) to discard the untitled project "
-                       "without a prompt, then CreateProject; restore with "
-                       "LoadProject afterward.",
+                   "SaveProject() on an Untitled project re-triggers the same modal. "
+                   "BROADER THAN 'UNTITLED', measured on Studio 21.0.4.5 "
+                   "(2026-08-12): with a NAMED project current (a conform project "
+                   "left open on the Deliver page), CreateProject returned None for "
+                   "a brand-new name and SaveProject returned False — with NO modal "
+                   "on screen, confirmed by screenshot, so the dialog is not the "
+                   "only mechanism. The connection was healthy throughout: "
+                   "OpenPage('edit') returned True in the same session, and moving "
+                   "to the Edit page did not help. Loading ANY clean project "
+                   "immediately unblocked it — CreateProject succeeded on the very "
+                   "next call. So the trigger is the current project, not the "
+                   "'Untitled' name, and a bare False/None is the only signal.",
+        "recommended": "LoadProject(any clean project) first, then CreateProject; "
+                       "restore the caller's project afterward. PREFER THAT OVER "
+                       "CloseProject, which this entry used to recommend: "
+                       "CloseProject DISCARDS unsaved changes, which is fine for a "
+                       "throwaway Untitled project but destroys work when the "
+                       "current project is a named one belonging to someone else's "
+                       "session — and the failure is NOT limited to Untitled "
+                       "projects, so that is a live risk. Never assume a bare None "
+                       "here means the name is taken; check "
+                       "GetProjectListInCurrentFolder().",
         "tags": ["project", "modal", "silent-failure"],
         "submit": "bug",
     },
@@ -663,11 +681,41 @@ API_TRUTH: List[Dict[str, Any]] = [
     {
         "symbol": "Transition create / copy / clone",
         "object": "Timeline / TimelineItem",
-        "reality": "The scripting API exposes no method to add, read, copy, or "
-                   "clone an edit transition (cross-dissolve, etc.). Transitions "
-                   "applied in the UI are invisible to and unmodifiable by scripts.",
-        "recommended": "Apply/duplicate transitions in the Resolve UI; no scripted "
-                       "equivalent exists.",
+        "reality": "There is no method to ADD or CLONE an edit transition — no "
+                   "AddTransition/CreateTransition/AddVideoTransition on Timeline "
+                   "or TimelineItem (dir(), 21.0.4.5). CORRECTION, measured on "
+                   "Studio 21.0.4.5 (2026-08-12): this entry previously said "
+                   "transitions applied in the UI are 'invisible to and "
+                   "unmodifiable by scripts'. BOTH HALVES WERE WRONG and are "
+                   "withdrawn. A transition IS a first-class timeline item: a "
+                   "12-frame Cross Dissolve applied through the Edit-page "
+                   "right-click menu enumerates in GetItemListInTrack('video', 1) "
+                   "as GetName()=='Cross Dissolve', GetStart()==86426, "
+                   "GetDuration()==12 — centered on a cut at 86432 — with a stable "
+                   "GetUniqueId() and a working GetTrackTypeAndIndex(). A "
+                   "transition authored offline into a .drp and imported reads "
+                   "IDENTICALLY, so the route that created it does not matter. It "
+                   "is also REMOVABLE: Timeline.DeleteClips([transition], False) "
+                   "returns True and deletes it, leaving both adjacent clips at "
+                   "their original starts and durations. THE DISCRIMINATOR between "
+                   "a transition item and a clip item is GetProperty(): a "
+                   "transition returns an EMPTY dict where a video clip returns 26 "
+                   "transform keys; it also has no MediaPoolItem and no Fusion "
+                   "comp. WHAT IS GENUINELY MISSING: creation, cloning, and any "
+                   "type/alignment/parameter detail — the transition's kind is "
+                   "knowable ONLY from its name string, and there is no way to "
+                   "read its alignment (centered/start/end) or edit its duration.",
+        "recommended": "Automated QC of existing transitions IS possible and is "
+                       "the main practical need — enumerate GetItemListInTrack, "
+                       "treat any item whose GetProperty() is empty and whose "
+                       "GetMediaPoolItem() is None as a transition, and read its "
+                       "name, start and duration. Removal is scriptable via "
+                       "Timeline.DeleteClips. To CREATE one, either apply it in the "
+                       "Resolve UI, or author it offline and import: the advanced "
+                       "server's drp place_transition writes a cross dissolve at an "
+                       "abutting cut ({track, atFrame, durationFrames}) and it "
+                       "round-trips into Resolve 21.0.4.5 reading back at the "
+                       "expected centered range.",
         "tags": ["missing-method", "timeline", "transition"],
         "submit": "missing",
     },