davinci-resolve-mcp 2.165.0 → 2.166.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 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.166.0 — E108: XMEML audio cross-fades conform and render
+
+The XMEML walker only looked at `<transitionitem>`s on VIDEO tracks, so an
+audio cross-fade vanished at parse and never reached the bridge that
+authors them (OTIO carried its audio Transition all along). Every audio
+track also walked as `A`, collapsing multi-track audio onto one lane where
+OTIO and AAF number `A`, `A2`, `A3` …
+
+### Fixed
+
+- **XMEML audio-track transitionitems attach** to the incoming audio event
+  exactly as video's do (one shared attach pass), and the bridge authors the
+  cross-fade. Render-measured on 19.1.3.7 against a control timeline: a 24f
+  `Cross Fade (+3dB)` from a −21 dBFS tone to a −41 dBFS tone ramps
+  −27.1 → −30.6 → −34.2 → −40.2 → −47.1 dBFS across the window in 0.25 s
+  RMS steps where the control steps hard at the cut.
+- **XMEML audio tracks number like OTIO/AAF** (`A`, `A2`, …), so the
+  bridge places each lane on its own audio track instead of stacking
+  everything on A1.
+- **`media_pool.capture_media_template` saves the current project before
+  switching to its scratch project.** `CreateProject` replaces the current
+  project, and an unsaved one is simply gone afterwards — the restore cannot
+  `LoadProject` a name that existed only in memory (measured: a freshly
+  created project with two imported timelines vanished, and Resolve fell
+  back to a transient "Untitled Project"). A failed save refuses the capture.
+
+### Measured (filed in api-limitations)
+
+- `ProjectManager.CreateProject` while an UNSAVED project is current
+  discards that project without error.
+
 ## What's New in v2.165.0 — E107: frame QC reads Resolve's own XML and samples clear of transitions
 
 The lineage store's `ingest_xml` was measured against a verbatim

package/README.md

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

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 37 missing capabilities, 50 bugs / unreliable behaviors.
+**Totals:** 38 missing capabilities, 50 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -309,6 +309,14 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** For round-trip QC prefer EXPORT_OTIO (carries audio, retimes as LinearTimeWarp/FreezeFrame, exact spans). When an EDL is the required deliverable, expect no audio (editorial.verify_roundtrip reports audioNotInExport) and resolve AX reels through the clip-name comments (parseEDL does). Use EXPORT_EDL — there is no EXPORT_CMX_3600 constant, and an unknown name reaches Export as a string that returns a bare False (timeline.export_timeline_checked now refuses it loudly).
 - **Tags:** timeline, export, edl, audio, silent-failure
 
+### ProjectManager.CreateProject (discards an unsaved current project)
+
+- **Object:** `ProjectManager`
+- **Signature:** `(projectName) -> Project`
+- **Behavior:** CreateProject replaces the CURRENT project with the new one. If the current project was never saved it is simply gone — no dialog headless, no error, and a later LoadProject of its name fails because the name existed only in memory (measured on Studio 19.1.3.7, E108: a project created via CreateProject with two imported timelines vanished when a media-template capture created its scratch project; the restore landed on a transient "Untitled Project" that is not in the project list either).
+- **Workaround / current handling:** SaveProject() before any CreateProject/LoadProject switch when the current project may be unsaved; the MCP's capture_media_template now does and refuses on a failed save.
+- **Tags:** project, lifecycle, silent-failure, headless
+
 ### Timeline.Export EXPORT_FCP_7_XML (no pproTicksIn, -1 edges under transitions)
 
 - **Object:** `Timeline`

package/install.py

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

package/resolve-advanced/README.md

@@ -98,7 +98,8 @@ Each dispatches on an `action`. Highlights:
 - **`media`** — media front-end / AE: `ingest_verify` (hash seal/verify/dupes-by-hash), `media_inventory`
   (fps/codec/colorspace/TC + card gaps), `sync` (TC picture↔sound + drift/MOS), `relink_manifest`,
   `rename_plan` (refuses camera originals) / `reel_normalize`, `turnover_package`, `project_hygiene`.
-- **`editorial`** — editorial integrity: `parse_interchange` (EDL/OTIO/XMEML natively, AAF via pyaaf2,
+- **`editorial`** — editorial integrity: `parse_interchange` (EDL/OTIO/XMEML natively — XMEML audio
+  cross-fades and numbered audio lanes included — AAF via pyaaf2,
   **.prproj via gunzip+XML** — pass the file PATH for the binary ones), `list_sequences` (one picker entry
   point across xml/edl/otio/drt/drp/aaf/prproj), `convert_to_interchange` (author OTIO/EDL/DRT that Resolve
   imports, from events or a parsed source — **the .prproj→Resolve conform bridge**, no Premiere needed;

package/resolve-advanced/server/editorial.mjs

@@ -370,6 +370,55 @@ export function parseXMEMLEvents(xml, opts = {}) {
       }
     }
   };
+  // Attach a track's <transitionitem> siblings to its walked events. Shared
+  // by VIDEO and AUDIO tracks (E108): audio cross-fades used to be dropped at
+  // parse because only the video walk looked at transitionitems, so an XMEML
+  // audio cross-fade never reached the bridge that authors them.
+  const attachTransitions = (t, label, before) => {
+  // <transitionitem> siblings: attach each to the INCOMING clip event —
+    // the one whose record-in falls inside the transition's span. Resolve's
+    // OWN XMEML importer writes these as elements that render INERT on
+    // 19.1.3 (measured E66: dip AND plain cross dissolve both played the
+    // outgoing clip through the window, hard cut at the end), so routing
+    // the turnover through assemble_from_interchange authors transitions
+    // that actually render where the host importer's do not.
+    const titems = t.transitionitem ? (Array.isArray(t.transitionitem) ? t.transitionitem : [t.transitionitem]) : [];
+    for (const tr of titems) {
+      const s = Number(tr.start), e2 = Number(tr.end);
+      if (!Number.isFinite(s) || !Number.isFinite(e2)) continue;
+      const effectId = (tr.effect && (tr.effect.effectid || tr.effect.name)) || 'Cross Dissolve';
+      const isBLev = (ev) => /^(BL|BLACK)$/i.test(String(ev.source || '').trim());
+      const inSpan = (ev) => ev.track === label && ev.recIn > s - 1 && ev.recIn <= e2;
+      // Prefer the PICTURE as the incoming: a Solid Color generatoritem in
+      // the same span is the fade's black side, not the clip fading in.
+      const incoming = events.slice(before).find((ev) => inSpan(ev) && !isBLev(ev)) || events.slice(before).find(inSpan);
+      // recStart carries the transitionitem's EXPLICIT record span start
+      // (sequence-relative) so the bridge reproduces the editor's actual
+      // alignment instead of assuming centered.
+      if (incoming) {
+        incoming.transition = { type: String(effectId), duration: e2 - s, recStart: s };
+        // No clip ENDS inside the span → nothing precedes: a fade-IN from
+        // black. Synthesize the zero-length BL leg (E91/E92) so the bridge
+        // authors a real black-to-picture dissolve instead of dropping it.
+        const outgoing = events.slice(before).find((ev) => ev.track === label && ev !== incoming && ev.recOut > s - 1 && ev.recOut <= e2);
+        if (!outgoing) {
+          events.push(evt({ index: idx++, track: label, source: 'BL', recIn: incoming.recIn, recOut: incoming.recIn, fps: seqRate }));
+        }
+      } else {
+        // No clip STARTS inside the span: a fade-OUT into black past the
+        // last clip. Attach the transition to a synthetic BL leg at the
+        // outgoing clip's end (the bridge grows it forward).
+        const outgoing = events.slice(before).find((ev) => ev.track === label && ev.recOut > s - 1 && ev.recOut <= e2);
+        if (outgoing) {
+          events.push(evt({
+            index: idx++, track: label, source: 'BL',
+            recIn: outgoing.recOut, recOut: outgoing.recOut,
+            transition: { type: String(effectId), duration: e2 - s, recStart: s }, fps: seqRate,
+          }));
+        }
+      }
+    }
+  };
   const seq = doc.xmeml && doc.xmeml.sequence;
   const media = seq && seq.media;
   if (media) {
@@ -396,52 +445,20 @@ export function parseXMEMLEvents(xml, opts = {}) {
       clipCursor = 0;
       if (t.clipitem) walk(t.clipitem, label);
       currentJunctions = [];
-      // <transitionitem> siblings: attach each to the INCOMING clip event —
-      // the one whose record-in falls inside the transition's span. Resolve's
-      // OWN XMEML importer writes these as elements that render INERT on
-      // 19.1.3 (measured E66: dip AND plain cross dissolve both played the
-      // outgoing clip through the window, hard cut at the end), so routing
-      // the turnover through assemble_from_interchange authors transitions
-      // that actually render where the host importer's do not.
-      const titems = t.transitionitem ? (Array.isArray(t.transitionitem) ? t.transitionitem : [t.transitionitem]) : [];
-      for (const tr of titems) {
-        const s = Number(tr.start), e2 = Number(tr.end);
-        if (!Number.isFinite(s) || !Number.isFinite(e2)) continue;
-        const effectId = (tr.effect && (tr.effect.effectid || tr.effect.name)) || 'Cross Dissolve';
-        const isBLev = (ev) => /^(BL|BLACK)$/i.test(String(ev.source || '').trim());
-        const inSpan = (ev) => ev.track === label && ev.recIn > s - 1 && ev.recIn <= e2;
-        // Prefer the PICTURE as the incoming: a Solid Color generatoritem in
-        // the same span is the fade's black side, not the clip fading in.
-        const incoming = events.slice(before).find((ev) => inSpan(ev) && !isBLev(ev)) || events.slice(before).find(inSpan);
-        // recStart carries the transitionitem's EXPLICIT record span start
-        // (sequence-relative) so the bridge reproduces the editor's actual
-        // alignment instead of assuming centered.
-        if (incoming) {
-          incoming.transition = { type: String(effectId), duration: e2 - s, recStart: s };
-          // No clip ENDS inside the span → nothing precedes: a fade-IN from
-          // black. Synthesize the zero-length BL leg (E91/E92) so the bridge
-          // authors a real black-to-picture dissolve instead of dropping it.
-          const outgoing = events.slice(before).find((ev) => ev.track === label && ev !== incoming && ev.recOut > s - 1 && ev.recOut <= e2);
-          if (!outgoing) {
-            events.push(evt({ index: idx++, track: label, source: 'BL', recIn: incoming.recIn, recOut: incoming.recIn, fps: seqRate }));
-          }
-        } else {
-          // No clip STARTS inside the span: a fade-OUT into black past the
-          // last clip. Attach the transition to a synthetic BL leg at the
-          // outgoing clip's end (the bridge grows it forward).
-          const outgoing = events.slice(before).find((ev) => ev.track === label && ev.recOut > s - 1 && ev.recOut <= e2);
-          if (outgoing) {
-            events.push(evt({
-              index: idx++, track: label, source: 'BL',
-              recIn: outgoing.recOut, recOut: outgoing.recOut,
-              transition: { type: String(effectId), duration: e2 - s, recStart: s }, fps: seqRate,
-            }));
-          }
-        }
-      }
+      attachTransitions(t, label, before);
     });
+    // Audio tracks number like OTIO/AAF (A, A2, A3 …) so multi-track audio
+    // keeps its lanes instead of collapsing onto A1 (E108), and their
+    // transitionitems attach the same way video's do.
     const atracks = media.audio && media.audio.track ? (Array.isArray(media.audio.track) ? media.audio.track : [media.audio.track]) : [];
-    for (const t of atracks) if (t.clipitem) walk(t.clipitem, 'A');
+    atracks.forEach((t, ai) => {
+      const label = ai === 0 ? 'A' : `A${ai + 1}`;
+      const before = events.length;
+      clipCursor = 0;
+      if (t.clipitem) walk(t.clipitem, label);
+      currentJunctions = [];
+      attachTransitions(t, label, before);
+    });
   }
   return events;
 }

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

@@ -86,7 +86,7 @@ const markerSchema = z.object({
 export const editorialTool = {
   name: 'editorial',
   description:
-    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively — incl. Resolve-written FCP7 -1 junction edges + Solid Color generators, and CMX FROM/TO CLIP NAME comments over the generic AX reel — + AAF via pyaaf2 + PRPROJ via gunzip+XML → normalized events incl. span-explicit transitions, BL fade legs, and freezes as zero-speed events (OTIO FreezeFrame, XMEML timeremap 0, PrProj in==out, AAF 0% motion effects); for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source; the EDL target writes CMX transition pairs incl. BL fades — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → moved/retimed/trimmed/replaced/new/gone PLUS the junction diff: transition_added/transition_dropped/transition_changed with fade in/out or dissolve, outgoing/incoming, span and duration/type/pre-roll deltas — zero-length CMX carrier lines and the BL legs that carry fades fold into the junction diff instead of reading as gone/new sources; events pair by closest record position, consumed once, so a source cut twice at two speeds compares instance to instance; + timing flags incl. transition_dropped and dropped_split_audio on any A-track), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base; BL-aware — black legs need no source, fades no black-side handles, and a fade-out tail requirement lands on the picture source), marker_roundtrip (markers with provenance tags), verify_roundtrip (input events vs re-export events -> pass/mismatches + fitted per-source TC offsets + marker compare w/ markersNotInExport honesty flag; FADE-AWARE: BL/Solid-Color legs merge out as blackSegments and fade-window boundary reshapes are excused into fadeReshapedBoundaries instead of failing; RETIME-AWARE: speed/reverse compare pairwise — EXPORT_OTIO carries an authored Sm2TimeMap back as LinearTimeWarp (measured), so a flattened/lost retime fails as drift geometry alone cannot catch; AUDIO-AWARE: declared audio events compare (a video-only export such as EXPORT_EDL flags audioNotInExport instead of failing) (channel legs deduped, mismatches tagged trackType audio) while the mirrored-A1 export of a video-only turnover stays informational; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
+    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively — incl. Resolve-written FCP7 -1 junction edges (paired in record order) + Solid Color generators, XMEML audio-track transitionitems as audio cross-fades on numbered lanes A/A2/…, and CMX FROM/TO CLIP NAME comments over the generic AX reel — + AAF via pyaaf2 + PRPROJ via gunzip+XML → normalized events incl. span-explicit transitions, BL fade legs, and freezes as zero-speed events (OTIO FreezeFrame, XMEML timeremap 0, PrProj in==out, AAF 0% motion effects); for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source; the EDL target writes CMX transition pairs incl. BL fades — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → moved/retimed/trimmed/replaced/new/gone PLUS the junction diff: transition_added/transition_dropped/transition_changed with fade in/out or dissolve, outgoing/incoming, span and duration/type/pre-roll deltas — zero-length CMX carrier lines and the BL legs that carry fades fold into the junction diff instead of reading as gone/new sources; events pair by closest record position, consumed once, so a source cut twice at two speeds compares instance to instance; + timing flags incl. transition_dropped and dropped_split_audio on any A-track), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base; BL-aware — black legs need no source, fades no black-side handles, and a fade-out tail requirement lands on the picture source), marker_roundtrip (markers with provenance tags), verify_roundtrip (input events vs re-export events -> pass/mismatches + fitted per-source TC offsets + marker compare w/ markersNotInExport honesty flag; FADE-AWARE: BL/Solid-Color legs merge out as blackSegments and fade-window boundary reshapes are excused into fadeReshapedBoundaries instead of failing; RETIME-AWARE: speed/reverse compare pairwise — EXPORT_OTIO carries an authored Sm2TimeMap back as LinearTimeWarp (measured), so a flattened/lost retime fails as drift geometry alone cannot catch; AUDIO-AWARE: declared audio events compare (a video-only export such as EXPORT_EDL flags audioNotInExport instead of failing) (channel legs deduped, mismatches tagged trackType audio) while the mirrored-A1 export of a video-only turnover stays informational; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
   async handler({ action, args }) {
     if (action === 'parse_interchange') {
       const p = parseSchema.parse(args);

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.165.0"
+VERSION = "2.166.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.165.0"
+VERSION = "2.166.0"
 
 import base64
 import os
@@ -13885,8 +13885,10 @@ def _capture_media_template(r, pm, p: Dict[str, Any]) -> Dict[str, Any]:
     <Element> + the timeline clips' <MediaRef> id. drt.assemble then
     TRANSPLANTS the cached element, which renders identically to native.
 
-    Switches the current project to a scratch project during capture and
-    switches back; requires the media file to exist locally.
+    Saves the current project, switches to a scratch project during capture
+    and switches back (an unsaved current project would otherwise be LOST —
+    CreateProject replaces it and the restore cannot load an unsaved name);
+    requires the media file to exist locally.
     """
     import hashlib
     import zipfile as _zipfile
@@ -13913,6 +13915,21 @@ def _capture_media_template(r, pm, p: Dict[str, Any]) -> Dict[str, Any]:
     except Exception:
         previous = None
 
+    # CreateProject(scratch) replaces the CURRENT project, and a current
+    # project that was never saved is simply gone afterwards — the restore
+    # below cannot LoadProject a name that exists only in memory (measured
+    # 2026-09-01, E108: a freshly created project with two imported timelines
+    # vanished; Resolve fell back to a transient "Untitled Project"). Save it
+    # first so the switch-back lands on the caller's own project.
+    if previous:
+        try:
+            if not pm.SaveProject():
+                return _err(
+                    f"could not save the current project {previous!r} before the capture switches "
+                    "away from it — an unsaved project would be lost; save it (project_manager.save) and retry"
+                )
+        except Exception as exc:  # pragma: no cover - API surprise
+            return _err(f"SaveProject before capture raised: {exc}")
     scratch = f"_mcp_media_tpl_{int(time.time())}"
     proj = pm.CreateProject(scratch)
     if not proj:
@@ -19829,7 +19846,7 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
       capture_media_template(media_path) -> {cache_path, media_ref}
         Captures the file's NATIVE Resolve media descriptors into
         ~/.config/davinci-resolve-mcp/media-templates/ via a disposable
-        project (switches projects during capture and switches back).
+        project (saves the current project, switches to a scratch project during capture and switches back — an unsaved current project would otherwise be lost).
         Offline drt.assemble then transplants them — the only measured way
         authored media actually RENDERS; synthesized descriptors import and
         read back fine but render black or 'Full resolution media not found'.

package/src/utils/api_truth.py

@@ -2794,6 +2794,28 @@ API_TRUTH: List[Dict[str, Any]] = [
         "submit": "missing",
         "mitigation": ["editorial.verify_roundtrip audioNotInExport", "timeline.export_timeline_checked"],
     },
+    {
+        "symbol": "ProjectManager.CreateProject (discards an unsaved current project)",
+        "object": "ProjectManager",
+        "signature": "(projectName) -> Project",
+        "reality": "CreateProject replaces the CURRENT project with the new "
+                   "one. If the current project was never saved it is simply "
+                   "gone — no dialog headless, no error, and a later "
+                   "LoadProject of its name fails because the name existed "
+                   "only in memory (measured on Studio 19.1.3.7, E108: a "
+                   "project created via CreateProject with two imported "
+                   "timelines vanished when a media-template capture created "
+                   "its scratch project; the restore landed on a transient "
+                   "\"Untitled Project\" that is not in the project list "
+                   "either).",
+        "recommended": "SaveProject() before any CreateProject/LoadProject "
+                       "switch when the current project may be unsaved; the "
+                       "MCP's capture_media_template now does and refuses on a "
+                       "failed save.",
+        "tags": ["project", "lifecycle", "silent-failure", "headless"],
+        "submit": "missing",
+        "mitigation": ["media_pool.capture_media_template saves first", "project_manager.save"],
+    },
     {
         "symbol": "Timeline.Export EXPORT_FCP_7_XML (no pproTicksIn, -1 edges under transitions)",
         "object": "Timeline",