davinci-resolve-mcp 2.115.0 → 2.116.0

package/docs/guides/native-drt-authoring.md

@@ -0,0 +1,110 @@
+# Native DRT Authoring — offline timelines that import AND render
+
+The `drt` tool in the advanced server (`drt.assemble`,
+`drt.assemble_from_interchange`) writes a **native-schema `.drt`** — a real
+Resolve project archive that `ImportTimelineFromFile` accepts — entirely
+offline. Unlike XML/AAF/OTIO interchange (which lands offline and needs a
+relink), a correctly assembled `.drt` arrives **linked and rendering**,
+because it carries native media-pool descriptors captured from a live Resolve.
+
+Everything below was measured live on Studio 19.1.3.7 and render-verified
+(frame luma via ffmpeg signalstats; audio via rendered RMS). Version numbers
+mark the release where each capability shipped.
+
+## The core doctrine: readback is blind, render is truth
+
+The recurring bug class of this entire subsystem: a structure that imports
+fine, **reads back fine through every API**, and renders black or silent.
+Structural readback cannot detect any of these:
+
+- media clips without native pool descriptors (black)
+- Fusion title comps whose bytes were edited offline (black — see below)
+- audio clips cloned from a donor with the donor's identity (silent)
+- audio tracks added by cloning (silent — no Fairlight strip)
+- a timemap in the wrong generation's encoding (plays at 100%, no warning)
+
+Always verify with a render: video by frame luma, audio by RMS in the target
+window. `render.verify_output` covers the container-level checks.
+
+## Prerequisites
+
+- **Per media file, once**: `media_pool.capture_media_template` (Python
+  server, live Resolve required once). It caches the file's native pool
+  `<Element>` + MediaRef under `~/.config/davinci-resolve-mcp/media-templates/`.
+  After that, all assembly for that file is fully offline.
+- Pass `targetAppVersion` (e.g. `"19.1.3"`) when the importing host is
+  pre-21: it selects the r19-generation templates and version stamps.
+
+## What you can author (all render-verified on 19.1.3)
+
+| Capability | Spec surface | Since |
+|---|---|---|
+| Media cuts, multi-source | `media: [{mediaFilePath, spec, cuts}]` | v2.106–2.107 |
+| Multi-track video (V2+ stacking) | `cuts[].track` (video-only above V1) | v2.112 |
+| Cross-dissolves | `transitions: [{track, atFrame, durationFrames}]` | v2.111 |
+| Audio cross-fades | `transitions[].trackType: 'audio'` | v2.116 |
+| Constant retimes, forward | `cuts[].speed` (e.g. `0.5`) | v2.113 |
+| Constant retimes, reverse | `cuts[].reverse` | v2.114 |
+| Audio placements, A1–A8 | `cuts[].audioOnly + track` | v2.115 |
+| Built-in generators | `elements: [{type:'generator', generatorName}]` | v2.110 |
+| Fusion titles | `elements: [{type:'title', text}]` — **21-gen hosts only** | v2.108 |
+
+`assemble_from_interchange` drives the same engine from an EDL / OTIO /
+FCP7-XML / AAF plus a `sourceMap`, and returns an honesty ledger
+(`authoredTransitions`, `droppedTransitions` with reasons, `authoredRetimes`,
+`flattenedRetimes`, `authoredAudioEvents`, `upperTrackCutsVideoOnly`).
+
+## The laws (why the constraints are what they are)
+
+**Fusion comp cache law (titles).** On 19.x, an imported Fusion comp renders
+only via the machine's disk cache, keyed to the comp blob's *exact
+compressed bytes*. Any offline byte change — even an identity recompression —
+misses the cache and renders black; live Fusion render of imported comps
+produces no frames on 19. Therefore offline title *text* cannot be authored
+for pre-21 hosts. The working flow: assemble everything else offline, then
+set title text post-import with `timeline.set_title_text` (live-verified on
+19.1.3). Generators are exempt — plain `Sm2TiGenerator`, no comp — and
+render everywhere (Solid Color, SMPTE Color Bar, Grey Scale verified).
+
+**Fairlight strip law (audio).** Audio tracks cannot be grown offline: the
+per-timeline Fairlight model (`FLStudioModelBA` in the pool's
+`Sm2Sequence.FieldsBlob`) holds one mixer strip per audio track, and a
+cloned track without a strip is mute. The r19 media template is captured
+with **8 mono audio tracks** (strips included); audio placements beyond
+track 8 refuse with instructions to re-capture a bigger template. Explicit
+`audioOnly` cuts suppress the A1 convenience mirror (which otherwise
+mirrors track-1 video cuts).
+
+**Timemap generation split (retimes).** `Sm2TimeMap` keyframes are protobuf
+points on 21 but keyed-dicts on 19, and 19 *silently ignores* the protobuf
+form (clip plays 100%). The r19 keyed encoder is byte-exact against
+Resolve's own output. The map spans the whole source stretched by 1/speed;
+the clip's `<In>`/`<Duration>` window into it in record-domain frames.
+Reverse is the same map with the Y endpoints swapped, and `In` then measures
+from the source end.
+
+**Timeline origin.** Template timelines start at frame 86400
+(01:00:00:00 @ 24fps). Clips placed before the origin are silently dropped
+by Resolve on import — `startFrame` is timeline-absolute.
+
+**Dissolve geometry.** A transition is authored only when the predecessor
+ends exactly at the cut and both sides have handle media for the centered
+span (incoming `srcIn ≥ dur/2`; outgoing `srcIn + dur + dur/2 ≤ frameCount`).
+Everything else stays in `droppedTransitions` with the reason.
+
+## Verification checklist for a delivered .drt
+
+1. `timeline.import_timeline_checked` — expect `linked == total` for media
+   (generators legitimately count as offline).
+2. Render a probe range; check frame luma at cut boundaries, dissolve
+   midpoints (expect the blend average), and retime windows.
+3. For audio: RMS per window (silence = -inf is a failed placement).
+4. Never trust `created_new: false` — a same-named timeline already in the
+   project is returned as "success" (internal-name-wins law).
+
+## References
+
+- `docs/reference/api-limitations.md` — the measured laws in report form
+- `resolve-advanced/vendor/drp-format/` — the codec layer (each module's
+  header documents its measured ground truth)
+- Guides: `conforming-an-avid-aaf.md` for the AAF ingest side

package/install.py

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

package/resolve-advanced/server/author-interchange.mjs

@@ -299,6 +299,7 @@ export function eventsToAssembleSpec(events, opts = {}) {
   const audioTrackNum = (t) => { const m = /^A(\d+)?$/.exec(String(t)); return m && m[1] ? parseInt(m[1], 10) : 1; };
   const audioPlacements = [];
   const audioRetimesSkipped = [];
+  const audioTransCandidates = [];
   for (const e of auds) {
     const recIn = ORIGIN + (toTl(e.recIn, e.fps) - minRec);
     const recOut = ORIGIN + (toTl(e.recOut, e.fps) - minRec);
@@ -309,7 +310,16 @@ export function eventsToAssembleSpec(events, opts = {}) {
     }
     const track = audioTrackNum(e.track);
     const cut = { startFrame: recIn, durationFrames, srcIn: toTl(e.srcIn ?? 0, e.fps), audioOnly: true, track };
-    audioPlacements.push({ start: recIn, end: recOut, index: e.index, track });
+    if (e.transition) {
+      let d = Math.max(2, toTl(e.transition.duration || 0, e.fps) || 2);
+      d += d % 2;
+      audioTransCandidates.push({
+        atFrame: recIn, durationFrames: d, track,
+        index: e.index, type: e.transition.type, rawDuration: e.transition.duration,
+        source: e.source, srcIn: cut.srcIn,
+      });
+    }
+    audioPlacements.push({ start: recIn, end: recOut, index: e.index, track, source: e.source, srcIn: cut.srcIn, durationFrames });
     if (!perSource.has(e.source)) perSource.set(e.source, []);
     perSource.get(e.source).push(cut);
   }
@@ -384,6 +394,29 @@ export function eventsToAssembleSpec(events, opts = {}) {
     }
     transitions.push({ track: c.track, atFrame: c.atFrame, durationFrames: c.durationFrames });
   }
+  // Audio cross-fades, same geometry rules (render-verified on 19.1.3.7 via
+  // the harvested cross-fade template: the highpass RMS ramps, not steps).
+  for (const c of audioTransCandidates) {
+    const prev = audioPlacements.find((pl) => pl.track === c.track && pl.end === c.atFrame);
+    if (!prev) {
+      droppedTransitions.push({ index: c.index, type: c.type, duration: c.rawDuration, trackType: 'audio', reason: 'no abutting predecessor at the cut' });
+      continue;
+    }
+    const half = c.durationFrames / 2;
+    const bHandle = c.srcIn >= half;
+    const aSpec = sourceMap[prev.source] && sourceMap[prev.source].spec;
+    const aFrames = aSpec && Number(aSpec.frameCount);
+    const aHandle = Number.isFinite(aFrames) ? prev.srcIn + prev.durationFrames + half <= aFrames : false;
+    if (!bHandle || !aHandle) {
+      droppedTransitions.push({
+        index: c.index, type: c.type, duration: c.rawDuration, trackType: 'audio',
+        reason: `insufficient handles for a centered ${c.durationFrames}f cross-fade` +
+          `${bHandle ? '' : ' (incoming srcIn < half)'}${aHandle ? '' : ' (outgoing tail media < half)'}`,
+      });
+      continue;
+    }
+    transitions.push({ track: c.track, atFrame: c.atFrame, durationFrames: c.durationFrames, trackType: 'audio' });
+  }
 
   return {
     spec: { timelineName, media, ...(transitions.length ? { transitions } : {}) },

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

@@ -46,7 +46,7 @@ const assembleSchema = z.object({
   spec: z
     .object({})
     .passthrough()
-    .describe("assembleTimeline spec: { timelineName?, media?: {mediaFilePath, spec:{width,height,frameCount,fps}, cuts:[{startFrame,durationFrames,srcIn?,track? (1-based video track; >1 = video-only, render-verified stacking),speed?/reverse? (constant retime, e.g. 0.5, forward or backwards; video-only; readback+render-verified on 19),audioOnly?+track? (explicit AUDIO placement on audio track 1-8; presence suppresses the A1 mirror; render-verified on 19)}]} | [same, ...] (multi-source needs media_pool.capture_media_template run once per file), elements?: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, generatorName? ('Solid Color'|'SMPTE Color Bar'|'Grey Scale' render-verified on 19), ...}], transitions? }. startFrame is timeline-absolute (origin 86400)."),
+    .describe("assembleTimeline spec: { timelineName?, media?: {mediaFilePath, spec:{width,height,frameCount,fps}, cuts:[{startFrame,durationFrames,srcIn?,track? (1-based video track; >1 = video-only, render-verified stacking),speed?/reverse? (constant retime, e.g. 0.5, forward or backwards; video-only; readback+render-verified on 19),audioOnly?+track? (explicit AUDIO placement on audio track 1-8; presence suppresses the A1 mirror; render-verified on 19)}]} | [same, ...] (multi-source needs media_pool.capture_media_template run once per file), transitions?: [{track, atFrame, durationFrames?, trackType? ('video' dissolve | 'audio' cross-fade, both render-verified on 19)}], elements?: [{type:'title'|'generator', track, startFrame, durationFrames?, text?, generatorName? ('Solid Color'|'SMPTE Color Bar'|'Grey Scale' render-verified on 19), ...}] }. startFrame is timeline-absolute (origin 86400)."),
   outputPath: z.string().describe('Absolute path where the importable .drt will be written'),
   targetAppVersion: z
     .union([z.string(), z.number()])

package/resolve-advanced/vendor/drp-format/__tests__/place-transition.test.js

@@ -44,5 +44,7 @@ test('placeTransition errors when no abutting boundary at atFrame', async () =>
 test('placeTransition validates args', async () => {
   const buf = await synth2();
   await assert.rejects(() => placeTransition(buf, { track: 1, atFrame: 100, durationFrames: 1 }), /durationFrames/);
-  await assert.rejects(() => placeTransition(buf, { track: 1, atFrame: 100, trackType: 'audio' }), /only video/);
+  // trackType 'audio' is now supported (harvested cross-fade template,
+  // v2.116.0); an unknown trackType still refuses.
+  await assert.rejects(() => placeTransition(buf, { track: 1, atFrame: 100, trackType: 'subtitle' }), /video or audio/);
 });

package/resolve-advanced/vendor/drp-format/assemble-timeline.js

@@ -181,6 +181,7 @@ async function assembleTimeline(spec = {}) {
     if (!tr || typeof tr !== 'object') throw new TypeError(`assembleTimeline: transitions[${i}] must be an object`);
     ({ buffer } = await placeTransition(buffer, {
       track: tr.track, atFrame: tr.atFrame, durationFrames: tr.durationFrames,
+      trackType: tr.trackType || 'video',
     }));
   }
 

package/resolve-advanced/vendor/drp-format/place-transition.js

@@ -33,6 +33,11 @@ function splitItems(itemsInner) {
 }
 
 const TEMPLATE_PATH = path.join(__dirname, 'templates', 'transition-cross-dissolve.xml');
+// Audio cross-fade, harvested from a live 19.1.3.7 XMEML import of an FCP7
+// KGAudioTransCrossFade (render-verified: the highpass RMS ramps through the
+// junction instead of stepping). PrettyType reads "Final Cut Pro 7" — that is
+// what Resolve itself stores for it, and it renders.
+const AUDIO_TEMPLATE_PATH = path.join(__dirname, 'templates', 'transition-cross-fade-r19.xml');
 
 const clipStart = (c) => { const m = c.match(/<Start>(\d+)<\/Start>/); return m ? parseInt(m[1], 10) : null; };
 const clipDuration = (c) => { const m = c.match(/<Duration>(\d+)<\/Duration>/); return m ? parseInt(m[1], 10) : null; };
@@ -45,7 +50,7 @@ const clipDuration = (c) => { const m = c.match(/<Duration>(\d+)<\/Duration>/);
  * @param {number} opts.track             - 1-based video track.
  * @param {number} opts.atFrame           - the cut frame (where one clip ends and the next begins).
  * @param {number} [opts.durationFrames=24] - transition length (even number recommended; centered).
- * @param {'video'} [opts.trackType='video'] - audio cross-fade uses a different template (not bundled).
+ * @param {'video'|'audio'} [opts.trackType='video'] - 'audio' places the harvested cross-fade (render-verified on 19.1.3).
  * @param {string} [opts.timelineUuid]
  * @returns {Promise<{buffer:Buffer, entry:string, timelineUuid:string, track:number,
  *   atFrame:number, start:number, durationFrames:number, transitionDbId:string|null}>}
@@ -55,7 +60,7 @@ async function placeTransition(drpInput, opts = {}) {
   if (!Number.isInteger(track) || track < 1) throw new TypeError('placeTransition: track must be a positive integer');
   if (!Number.isInteger(atFrame)) throw new TypeError('placeTransition: atFrame must be an integer');
   if (!Number.isInteger(durationFrames) || durationFrames < 2) throw new TypeError('placeTransition: durationFrames must be an integer >= 2');
-  if (trackType !== 'video') throw new Error('placeTransition: only video cross-dissolve is supported (no bundled audio template)');
+  if (trackType !== 'video' && trackType !== 'audio') throw new Error('placeTransition: trackType must be video or audio');
 
   const zip = await loadDrpZip(drpInput);
   const { entry, xml: seqXml, seqId } = await selectTargetSeq(zip, timelineUuid);
@@ -71,7 +76,7 @@ async function placeTransition(drpInput, opts = {}) {
   }
   if (leftIdx < 0) throw new Error(`placeTransition: no abutting clip boundary at frame ${atFrame} on track ${track}`);
 
-  let trans = fs.readFileSync(TEMPLATE_PATH, 'utf8').trim();
+  let trans = fs.readFileSync(trackType === 'audio' ? AUDIO_TEMPLATE_PATH : TEMPLATE_PATH, 'utf8').trim();
   trans = freshDbIds(trans);
   const start = atFrame - Math.floor(durationFrames / 2); // centered (AlignmentType 2)
   trans = trans.replace(/<Start>\d+<\/Start>/, `<Start>${start}</Start>`);

package/resolve-advanced/vendor/drp-format/templates/transition-cross-fade-r19.xml

@@ -0,0 +1,22 @@
+<Element>
+<Sm2TiTransition DbId="43e55250-3117-4f6e-abf0-ce028e94bf71">
+       <FieldsBlob>000000020000001b8012180000002c789c636660640001e62b75aa0c04000033c3017f</FieldsBlob>
+       <PrettyType>Final Cut Pro 7</PrettyType>
+       <Name/>
+       <Start>36</Start>
+       <Duration>24</Duration>
+       <LinkedItemSync/>
+       <WasDisbanded>false</WasDisbanded>
+       <MarkersBA/>
+       <UiMemento>0</UiMemento>
+       <Flags>0</Flags>
+       <PriorityIndex>0</PriorityIndex>
+       <EffectFiltersBA>00000002000001418128b52ffd60ea02b50900d24e3631608bda00016b1886611886618aaa90c45a8b2c4bb74e225968cc77bbadcdb43f34bdb7510008cd286032991041dcafba3a6db563c78e1f207ad278bd56901d3be66054645e53f64ec70e0cfdd6395ec67bbd5ad6a24a3d7f9d724c23acdc237c3969bcd14eafb71f24ba8e1ffab3d3eb4423ac3212140da3e3030d6c4098b087fe98b5b46efaa5cf4b7da7f3948a06887acc1863ab5b85577fe4cb10e35c6c4c1b8b08035e8d6996843765b48b674648a9f9ac295016da65d268eb7bb08f0c615802d148a3258514040c7448221f13001601828924325a012300e9f0abc6e90af86f499c4a043085b2b044a134bcb479940460f4f9df4213e27805a1a8862fe8bcb86058bb0b23aeab01486d4073cdcda64fc1d02980a688b20aada10ad6ead65663955acbce363a856d7330570bd2da6206</EffectFiltersBA>
+       <ImportExportMetadataBA/>
+       <RenderTextEnabled>true</RenderTextEnabled>
+       <RenderTextGanged>true</RenderTextGanged>
+       <RenderTextPrefixed>true</RenderTextPrefixed>
+       <AlignmentType>2</AlignmentType>
+       <Position>2</Position>
+      </Sm2TiTransition>
+</Element>

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.115.0"
+VERSION = "2.116.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.115.0"
+VERSION = "2.116.0"
 
 import base64
 import os