davinci-resolve-mcp 2.114.0 → 2.115.0

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 33 missing capabilities, 43 bugs / unreliable behaviors.
+**Totals:** 33 missing capabilities, 44 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -526,6 +526,13 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #171](https://github.com/samuelgursky/davinci-resolve-mcp/issues/171)
 - **Tags:** timeline, import, silent-failure, unreliable-return
 
+### Audio tracks cannot be grown in an imported timeline; Fairlight strips live in the pool Sm2Sequence.FieldsBlob
+
+- **Object:** `Sm2TiTrack (audio) / FLStudioModelBA`
+- **Behavior:** An audio track added to a SeqContainer by cloning imports fine, reads back fine (track count, items, everything), and renders SILENT. The per-timeline Fairlight model (FLStudioModelBA, ~7KB compressed to ~420KB, inside the media pool's Sm2Sequence.FieldsBlob) holds one strip per audio track, and a track without a strip is mute. Measured by elimination on 19.1.3.7: clip byte-identical to a live-authored one, track byte-identical (SubType is the CHANNEL FORMAT code - 1=mono - not an ordinal), pool entry shared with a playing A1 clip - still silent; only a timeline whose template was CAPTURED with the tracks plays.
+- **Workaround / current handling:** Never clone audio tracks offline. Capture the template with the audio tracks already present (the r19 media template carries 8 mono tracks with valid strips; drt.assemble audioOnly cuts land on them and render at native level). Refuse placements beyond the captured ceiling. Audio aliveness is readback-blind: verify by rendered RMS, not structure.
+- **Tags:** fairlight, audio, import, silent-failure, drt
+
 ### MediaTimemapBA keyframes are generation-split; 19.x silently ignores the R21 protobuf form
 
 - **Object:** `Sm2TimeMap (per-clip retime blob)`

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.114.0"
+VERSION = "2.115.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.114.0",
+  "version": "2.115.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

@@ -207,7 +207,9 @@ export function eventsToOTIO(events, opts = {}) {
  * dropped transitions (cross-dissolves are AUTHORED when the predecessor
  * abuts the cut and both sides have handle media — render-verified on
  * 19.1.3.7; otherwise dropped with the reason, as a cut at the boundary),
- * and skipped audio events (cuts carry linked A1 audio already).
+ * and audio: A-track events are AUTHORED as audioOnly cuts on their own
+ * audio tracks (render-verified; the template carries 8 Fairlight-valid
+ * audio tracks) — their presence suppresses the A1 convenience mirror.
  *
  * @param {Array} events - normalized events (parseInterchange shape)
  * @param {object} opts
@@ -226,11 +228,13 @@ export function eventsToAssembleSpec(events, opts = {}) {
     throw new TypeError('eventsToAssembleSpec: sourceMap {reel: {mediaFilePath, spec}} is required');
   }
   const ORIGIN = 86400;
-  const vids = events.filter((e) => e.track !== 'A' && e.recIn != null && e.recOut != null);
-  const audioSkipped = events.length - vids.length;
+  const isAudio = (t) => /^A\d*$/.test(String(t || ''));
+  const vids = events.filter((e) => !isAudio(e.track) && e.recIn != null && e.recOut != null);
+  const auds = events.filter((e) => isAudio(e.track) && e.recIn != null && e.recOut != null);
+  const audioSkipped = events.length - vids.length - auds.length;
   if (!vids.length) throw new Error('eventsToAssembleSpec: no video events with record ranges');
 
-  const unmapped = [...new Set(vids.map((e) => e.source).filter((srcName) => !sourceMap[srcName]))];
+  const unmapped = [...new Set([...vids, ...auds].map((e) => e.source).filter((srcName) => !sourceMap[srcName]))];
   if (unmapped.length) {
     throw new Error(
       `eventsToAssembleSpec: unmapped source reel(s): ${unmapped.join(', ')} — ` +
@@ -287,6 +291,44 @@ export function eventsToAssembleSpec(events, opts = {}) {
     perSource.get(e.source).push(cut);
   }
 
+  // Audio events become explicit audioOnly cuts on their own audio tracks —
+  // this SUPPRESSES the convenience A1 mirror downstream (explicit audio
+  // wins). Render-verified on 19.1.3.7: an offline A3 cut plays at the
+  // native control level through the captured 8-audio-track template's
+  // Fairlight strips. Retimed audio is not authored (no audio timemap yet).
+  const audioTrackNum = (t) => { const m = /^A(\d+)?$/.exec(String(t)); return m && m[1] ? parseInt(m[1], 10) : 1; };
+  const audioPlacements = [];
+  const audioRetimesSkipped = [];
+  for (const e of auds) {
+    const recIn = ORIGIN + (toTl(e.recIn, e.fps) - minRec);
+    const recOut = ORIGIN + (toTl(e.recOut, e.fps) - minRec);
+    const durationFrames = recOut - recIn;
+    if (durationFrames <= 0) continue;
+    if ((e.speed ?? 100) !== 100 || e.reverse) {
+      audioRetimesSkipped.push({ index: e.index, source: e.source, speed: e.speed, reverse: !!e.reverse, reason: 'audio retime not supported — played at 100%' });
+    }
+    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 (!perSource.has(e.source)) perSource.set(e.source, []);
+    perSource.get(e.source).push(cut);
+  }
+  audioPlacements.sort((a, b) => a.start - b.start);
+  const audByTrack = new Map();
+  for (const pl of audioPlacements) {
+    if (!audByTrack.has(pl.track)) audByTrack.set(pl.track, []);
+    audByTrack.get(pl.track).push(pl);
+  }
+  for (const [trk, pls] of audByTrack) {
+    for (let i = 1; i < pls.length; i += 1) {
+      if (pls[i].start < pls[i - 1].end) {
+        throw new Error(
+          `eventsToAssembleSpec: audio events ${pls[i - 1].index} and ${pls[i].index} ` +
+          `overlap on audio track ${trk} after frame conversion — one track cannot hold both.`);
+      }
+    }
+  }
+
   // Overlap is judged PER VIDEO TRACK — V2 stacking over V1 is legitimate
   // conform geometry (render-verified: an upper-track clip covers the lower).
   placements.sort((a, b) => a.start - b.start);
@@ -349,6 +391,8 @@ export function eventsToAssembleSpec(events, opts = {}) {
       videoEvents: vids.length,
       sources: media.length,
       audioEventsSkipped: audioSkipped,
+      authoredAudioEvents: audioPlacements.length,
+      audioRetimesSkipped,
       upperTrackCutsVideoOnly: placements.filter((pl) => pl.track > 1).length,
       flattenedRetimes,
       authoredRetimes,

package/resolve-advanced/server/editorial.mjs

@@ -91,7 +91,9 @@ export function parseEDL(text, opts = {}) {
     const head = tokens.slice(0, tokens.indexOf(tcs[tcs.length - 4]));
     const [eventNum, reel, channel, transition] = head;
     const dur = transition && transition !== 'C' ? Number(head[4]) : 0;
-    const track = /A/i.test(channel || '') && !/V/i.test(channel || '') ? 'A' : 'V';
+    const chan = String(channel || '');
+    const am = /^A(\d+)?$/i.exec(chan);
+    const track = am && !/V/i.test(chan) ? (am[1] && am[1] !== '1' ? `A${am[1]}` : 'A') : (/A/i.test(chan) && !/V/i.test(chan) ? 'A' : 'V');
     events.push(
       evt({
         index: Number(eventNum),
@@ -117,11 +119,13 @@ export function parseOTIO(otio, opts = {}) {
   const events = [];
   let idx = 1;
   let vNum = 0;
+  let aNum = 0;
   for (const track of tracks) {
     const isAudio = track.kind === 'Audio';
-    if (!isAudio) vNum += 1;
-    // First video track stays 'V' (compat); higher tracks are 'V2', 'V3', …
-    const kind = isAudio ? 'A' : (vNum === 1 ? 'V' : `V${vNum}`);
+    if (isAudio) aNum += 1; else vNum += 1;
+    // First track of each kind keeps the bare letter (compat); higher tracks
+    // are numbered ('V2', 'A2', …).
+    const kind = isAudio ? (aNum === 1 ? 'A' : `A${aNum}`) : (vNum === 1 ? 'V' : `V${vNum}`);
     let rec = 0;
     for (const child of track.children || []) {
       const schema = child.OTIO_SCHEMA || '';

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)}]} | [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), 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)."),
   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/assemble-timeline.js

@@ -114,6 +114,14 @@ async function assembleTimeline(spec = {}) {
     sources.forEach((src, i) => {
       (src.cuts || []).forEach((cut) => {
         const out = mediaRefs[i] ? { ...cut, mediaRef: mediaRefs[i] } : { ...cut };
+        if (cut.audioOnly) {
+          out.srcMeta = {
+            name: src.mediaFilePath.split('/').pop(),
+            mediaFilePath: src.mediaFilePath,
+            fps: Math.round(src.spec.fps || 24),
+            frameCount: src.spec.frameCount,
+          };
+        }
         if (cut.reverse || (cut.speed !== undefined && cut.speed !== 1)) {
           // Constant-speed retime (forward only). The Sm2TimeMap spans the
           // whole source stretched by 1/speed; the clip windows into it with

package/resolve-advanced/vendor/drp-format/cut-media.js

@@ -38,6 +38,10 @@ const { clipDbId, setClipStart, setClipDuration, setClipIn } = require('./splice
  *   track is the 1-based VIDEO track (default 1); missing tracks are grown as
  *   empty clones. Cuts on track > 1 are placed VIDEO-ONLY — their audio would
  *   overlap the track-1 cuts' audio on A1 (the template has a single A1).
+ *   audioOnly:true makes a cut an AUDIO clip placement instead (track then
+ *   indexes AUDIO tracks, grown as needed) — and the presence of ANY
+ *   audioOnly cut suppresses the implicit A1 mirror of track-1 video cuts
+ *   (explicit audio wins over the convenience mirror).
  * @param {string} [opts.timelineUuid]
  * @returns {Promise<{buffer: Buffer, cutCount: number, clipDbIds: string[]}>}
  */
@@ -79,6 +83,26 @@ async function cutSourceIntoClips(drpInput, opts = {}) {
       // element instead of the donor's.
       c = c.replace(/<MediaRef>[0-9a-f-]{36}<\/MediaRef>/, `<MediaRef>${cut.mediaRef}</MediaRef>`);
     }
+    if (cut.audioOnly && cut.srcMeta) {
+      // An audio-only clone must carry ITS OWN source identity — a live
+      // A2-placed clip (harvested via AppendToTimeline mediaType:2) differs
+      // from a donor clone in Name, MediaFilePath, MediaFrameRate (the
+      // template donor's was 29.97!), the identity MediaTimemapBA extent,
+      // and FieldsBlob. A clone keeping donor values imports and reads back
+      // fine but renders SILENT off A1.
+      const { name, mediaFilePath, fps, frameCount } = cut.srcMeta;
+      c = c.replace(/<Name>[\s\S]*?<\/Name>/, `<Name>${name}</Name>`);
+      c = c.replace(/<MediaFilePath>[\s\S]*?<\/MediaFilePath>/, `<MediaFilePath>${mediaFilePath}</MediaFilePath>`);
+      const rate = Buffer.alloc(16);
+      rate.writeDoubleLE(fps, 0);
+      c = c.replace(/<MediaFrameRate>[0-9a-fA-F]*<\/MediaFrameRate>/, `<MediaFrameRate>${rate.toString('hex')}</MediaFrameRate>`);
+      const idm = Buffer.alloc(9);
+      idm.writeUInt8(0x02, 0);
+      idm.writeDoubleBE((frameCount - 1) / fps, 1);
+      c = c.replace(/<MediaTimemapBA>[0-9a-fA-F]*<\/MediaTimemapBA>/, `<MediaTimemapBA>${idm.toString('hex')}</MediaTimemapBA>`);
+      // Generic audio-clip FieldsBlob, verbatim from the live A2 harvest.
+      c = c.replace(/<FieldsBlob>[0-9a-fA-F]*<\/FieldsBlob>/, '<FieldsBlob>0000000200000005800a022001</FieldsBlob>');
+    }
     if (cut.timemap) {
       // Constant-speed retime: swap the identity MediaTimemapBA for the
       // caller-built Sm2TimeMap (r19 keyed form render/readback-verified;
@@ -96,19 +120,44 @@ async function cutSourceIntoClips(drpInput, opts = {}) {
     if (!clips.length) continue; // audio-less media: nothing to cut on A1
     const donor = clips[0];
     if (trackType === 'audio') {
-      // A1 mirrors track-1 video cuts only; higher video tracks stay video-only,
-      // and so do RETIMED cuts (the audio clone would need its own timemap and
-      // pitch handling — video-only is stated, not silent).
-      const a1 = cuts.filter((cut) => (cut.track ?? 1) === 1 && !cut.timemap).map((cut) => cloneCut(donor, cut));
-      tracks[0] = setItemsInner(tracks[0], a1.join(''));
+      const audioCuts = cuts.filter((cut) => cut.audioOnly);
+      if (audioCuts.length) {
+        // Explicit audio placements: grow audio tracks and place per track;
+        // the implicit A1 mirror is suppressed (explicit audio wins).
+        const maxA = Math.max(1, ...audioCuts.map((cut) => cut.track ?? 1));
+        if (maxA > tracks.length) {
+          // Audio tracks CANNOT be grown by cloning: the per-timeline
+          // Fairlight model (FLStudioModelBA inside the pool's
+          // Sm2Sequence.FieldsBlob) holds one strip per track, and a cloned
+          // track without a strip imports fine, reads back fine, and renders
+          // SILENT (measured). The r19 media template is captured with 8
+          // audio tracks (valid strips included); beyond that, refuse.
+          throw new Error(
+            `cutSourceIntoClips: audio track ${maxA} exceeds the template's ${tracks.length} ` +
+            'audio tracks — audio tracks cannot be grown offline (no Fairlight strip = silent). ' +
+            'Re-capture a template with more audio tracks to raise the ceiling.');
+        }
+        for (let t = 1; t <= tracks.length; t += 1) {
+          const mine = audioCuts.filter((cut) => (cut.track ?? 1) === t);
+          if (t > 1 && !mine.length) continue;
+          tracks[t - 1] = setItemsInner(tracks[t - 1], mine.map((cut) => cloneCut(donor, cut)).join(''));
+        }
+      } else {
+        // A1 mirrors track-1 video cuts only; higher video tracks stay
+        // video-only, and so do RETIMED cuts (the audio clone would need its
+        // own timemap and pitch handling — video-only is stated, not silent).
+        const a1 = cuts.filter((cut) => (cut.track ?? 1) === 1 && !cut.timemap).map((cut) => cloneCut(donor, cut));
+        tracks[0] = setItemsInner(tracks[0], a1.join(''));
+      }
       xml = replaceTrackVec(xml, trackType, match, tracks);
       continue;
     }
-    const maxTrack = Math.max(1, ...cuts.map((cut) => cut.track ?? 1));
+    const vCuts = cuts.filter((cut) => !cut.audioOnly);
+    const maxTrack = Math.max(1, ...vCuts.map((cut) => cut.track ?? 1));
     const cloneSource = tracks[0];
     while (tracks.length < maxTrack) tracks.push(emptyTrackClone(cloneSource));
     for (let t = 1; t <= tracks.length; t += 1) {
-      const mine = cuts.filter((cut) => (cut.track ?? 1) === t);
+      const mine = vCuts.filter((cut) => (cut.track ?? 1) === t);
       if (t > 1 && !mine.length) continue; // grown-empty or untouched track keeps its items
       const clones = mine.map((cut) => cloneCut(donor, cut));
       for (const c of clones) clipDbIds.push(clipDbId(c));

package/src/granular/common.py

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

package/src/utils/api_truth.py

@@ -1914,6 +1914,32 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "structural readback cannot see this class.",
         "tags": ["media-pool", "import", "render", "silent-failure", "readback"],
     },
+    {
+        "symbol": "Audio tracks cannot be grown in an imported timeline; Fairlight strips live in the pool Sm2Sequence.FieldsBlob",
+        "object": "Sm2TiTrack (audio) / FLStudioModelBA",
+        "reality": "An audio track added to a SeqContainer by cloning "
+                   "imports fine, reads back fine (track count, items, "
+                   "everything), and renders SILENT. The per-timeline "
+                   "Fairlight model (FLStudioModelBA, ~7KB compressed to "
+                   "~420KB, inside the media pool's Sm2Sequence.FieldsBlob) "
+                   "holds one strip per audio track, and a track without a "
+                   "strip is mute. Measured by elimination on 19.1.3.7: "
+                   "clip byte-identical to a live-authored one, track "
+                   "byte-identical (SubType is the CHANNEL FORMAT code - "
+                   "1=mono - not an ordinal), pool entry shared with a "
+                   "playing A1 clip - still silent; only a timeline whose "
+                   "template was CAPTURED with the tracks plays.",
+        "recommended": "Never clone audio tracks offline. Capture the "
+                       "template with the audio tracks already present "
+                       "(the r19 media template carries 8 mono tracks with "
+                       "valid strips; drt.assemble audioOnly cuts land on "
+                       "them and render at native level). Refuse placements "
+                       "beyond the captured ceiling. Audio aliveness is "
+                       "readback-blind: verify by rendered RMS, not "
+                       "structure.",
+        "tags": ["fairlight", "audio", "import", "silent-failure", "drt"],
+        "submit": "bug",
+    },
     {
         "symbol": "MediaTimemapBA keyframes are generation-split; 19.x silently ignores the R21 protobuf form",
         "object": "Sm2TimeMap (per-clip retime blob)",