davinci-resolve-mcp 2.127.0 → 2.128.0

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

@@ -51,6 +51,7 @@ window. `render.verify_output` covers the container-level checks.
 | Timeline markers | `spec.markers` (16 colors, notes, durations, customData) | v2.118 |
 | Turnover markers | EDL `* LOC:` locators + OTIO markers → authored | v2.119 |
 | TC-bearing sources (AAF route) | native clip capture (`MediaStartTime`), channel-leg merge | v2.120–2.122 |
+| Subtitles | `spec.subtitles` / `spec.subtitlesSrt` (raw SRT) | v2.128 |
 | Fusion titles | `elements: [{type:'title', text}]` — **21-gen hosts only** | v2.108 |
 
 `assemble_from_interchange` drives the same engine from an EDL / OTIO /

package/docs/reference/api-limitations.md

@@ -557,7 +557,7 @@ values, or automation-hostile modal prompts.
 ### MediaTimemapBA keyframes are generation-split; 19.x silently ignores the R21 protobuf form
 
 - **Object:** `Sm2TimeMap (per-clip retime blob)`
-- **Behavior:** Resolve 21 encodes a retimed clip's KeyframesBA as protobuf points; Resolve 19.1.3 encodes it as a keyed-dict of keyed-dict keyframes ({interp, YOut, YIn, Y, XOut, XIn, X}). On import, 19 SILENTLY IGNORES the protobuf form — the clip reads back and plays at 100% with no warning (measured: identical timelines, one per form; protobuf → source 0..96 over 96 frames, keyed → source 0..48 over 96 frames and a live 50% render). The map spans the WHOLE source stretched by 1/speed; the clip's <In>/<Duration> window into it in RECORD frames (srcIn converts by /speed). REVERSE is the same envelope with the Y endpoints swapped - kf0=(0,YMax), kf1=(XMax,0) - and In then measures from the source END: (frames - srcIn - dur*speed)/speed (measured: a reversed srcIn-24 dur-48 cut reads back source 71->23). A FLAT map (both keyframes at the same Y - a freeze) is the one shape where readback and render DIVERGE: the item reads back frozen (source 96..96) but renders MOVING (48/48 unique frames measured). Do not author freezes as flat timemaps.
+- **Behavior:** Resolve 21 encodes a retimed clip's KeyframesBA as protobuf points; Resolve 19.1.3 encodes it as a keyed-dict of keyed-dict keyframes ({interp, YOut, YIn, Y, XOut, XIn, X}). On import, 19 SILENTLY IGNORES the protobuf form — the clip reads back and plays at 100% with no warning (measured: identical timelines, one per form; protobuf → source 0..96 over 96 frames, keyed → source 0..48 over 96 frames and a live 50% render). The map spans the WHOLE source stretched by 1/speed; the clip's <In>/<Duration> window into it in RECORD frames (srcIn converts by /speed). REVERSE is the same envelope with the Y endpoints swapped - kf0=(0,YMax), kf1=(XMax,0) - and In then measures from the source END: (frames - srcIn - dur*speed)/speed (measured: a reversed srcIn-24 dur-48 cut reads back source 71->23). A FLAT map (both keyframes at the same Y - a freeze) is the one shape where readback and render DIVERGE: the item reads back frozen (source 96..96) but renders MOVING (48/48 unique frames measured). Do not author freezes as flat timemaps. AUDIO clips ignore the timemap entirely: a 50% keyed map on an imported audio clip reads back retimed (source 0..48 over 96 record frames) but RENDERS at 100% - unchanged pitch and spectrum (highpass/lowpass split identical to the 1x reference).
 - **Workaround / current handling:** Author retimes for pre-21 hosts with the keyed form (drt.assemble cuts[].speed does this; encoder byte-exact against a live 19.1.3.7 harvest). Treat any cross-generation timemap as unverified until a readback shows the retimed source range.
 - **Tags:** retime, import, silent-failure, drt
 

package/install.py

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

@@ -329,7 +329,7 @@ export function eventsToAssembleSpec(events, opts = {}) {
     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%' });
+      audioRetimesSkipped.push({ index: e.index, source: e.source, speed: e.speed, reverse: !!e.reverse, reason: 'audio retime not authorable — the audio engine ignores the clip timemap (measured: reads back retimed, renders 100%); played at 100%' });
     }
     const track = audioTrackNum(e.track);
     const cut = { startFrame: recIn, durationFrames, srcIn: toTl(e.srcIn ?? 0, e.fps), audioOnly: true, track };

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

@@ -50,7 +50,7 @@ const assembleSchema = z.object({
   spec: z
     .object({})
     .passthrough()
-    .describe("assembleTimeline spec: { timelineName?, startFrame? (timeline start frame @24, default 86400=01:00:00:00 — sets the start TIMECODE, render-verified on 19), 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)}], markers?: [{frame (timeline-absolute), color? (16 names), name?, note?, duration?, customData?}] (readback-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)."),
+    .describe("assembleTimeline spec: { timelineName?, startFrame? (timeline start frame @24, default 86400=01:00:00:00 — sets the start TIMECODE, render-verified on 19), 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)}], markers?: [{frame (timeline-absolute), color? (16 names), name?, note?, duration?, customData?}] (readback-verified on 19), subtitles?: [{startFrame (timeline-absolute), durationFrames, text}] + subtitlesSrt? (raw SRT, cues anchor at the origin; readback-verified on 19; angle-bracket runs read as SRT markup), 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/assemble-timeline.js

@@ -27,6 +27,7 @@ const JSZip = require('jszip');
 const { cutSourceIntoClips } = require('./cut-media');
 const { buildConstantSpeedTimemapKeyed } = require('./media-timemap');
 const { encodeTimelineMarkersBlob } = require('./timeline-markers-blob');
+const { placeSubtitles, parseSrt } = require('./place-subtitles');
 const { randomUUID } = require('node:crypto');
 const { placeFusionTitle } = require('./place-fusion-title');
 const { placeGenerator } = require('./place-generator');
@@ -198,6 +199,23 @@ async function assembleTimeline(spec = {}) {
     }));
   }
 
+  // Subtitles: plain Sm2TiGenerator items (text in <Name>, no blobs — the
+  // cache law does not apply; the payload is API-visible after import).
+  // spec.subtitles frames are timeline-ABSOLUTE; spec.subtitlesSrt is raw SRT
+  // text whose cues anchor at the origin.
+  let subtitles = Array.isArray(spec.subtitles) ? [...spec.subtitles] : [];
+  if (typeof spec.subtitlesSrt === 'string' && spec.subtitlesSrt.length) {
+    subtitles.push(...parseSrt(spec.subtitlesSrt, 24).map((c) => ({ ...c, startFrame: c.startFrame + originFrame })));
+  }
+  if (subtitles.length) {
+    for (const sub of subtitles) {
+      if (!Number.isInteger(sub.startFrame) || sub.startFrame < originFrame) {
+        throw new RangeError(`assembleTimeline: subtitle at frame ${sub.startFrame} is before the timeline origin ${originFrame}`);
+      }
+    }
+    ({ buffer } = await placeSubtitles(buffer, { subtitles }));
+  }
+
   if (Array.isArray(spec.markers) && spec.markers.length) {
     // Timeline markers ride in project.xml as a Sm2SequenceLockableBlob whose
     // BlobOwner is the timeline's Sm2Sequence DbId (the uuid every track's

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

@@ -0,0 +1,128 @@
+/**
+ * place-subtitles — author SUBTITLE items into a timeline inside a real .drp,
+ * offline.
+ *
+ * Ground truth (harvested live from Studio 19.1.3.7, an SRT appended via the
+ * scripting API and re-exported): a subtitle is the SIMPLEST timeline item in
+ * the schema — a plain `<Sm2TiGenerator>` with `<PrettyType>Subtitle` and the
+ * CUE TEXT in `<Name>`, all blob fields empty, sitting in a `<Sm2TiTrack>` of
+ * `<Type>2</Type>` inside `<SubtitleTrackVec>`. No Fusion comp, so the
+ * byte-keyed comp-cache law does not apply; the text is API-visible after
+ * import (readback IS meaningful here — the payload is the Name).
+ *
+ * The r19 template ships `<SubtitleTrackVec/>` self-closed; this module
+ * synthesizes the vec + track from the harvested shape (track FieldsBlob is
+ * the same keyed NumLayers=0 dict every track carries) and reuses the
+ * timeline's shared <Sequence> uuid.
+ *
+ * Caveat (measured): Resolve treats angle-bracket runs in cue text as SRT
+ * formatting markup — an unknown tag like <escaped> is STRIPPED from the
+ * displayed/readback name. That is standard subtitle semantics, not a loss
+ * in this writer (the XML itself carries the text escaped and intact).
+ *
+ * @module drp-format/place-subtitles
+ */
+
+const crypto = require('node:crypto');
+const { escapeXml } = require('./xml-builder');
+const { loadDrpZip, selectTargetSeq } = require('./seq-surgery');
+
+// Harvested track FieldsBlob: keyed dict { NumLayers: int32 0 } — identical
+// across video/audio/subtitle tracks.
+const TRACK_FIELDS_BLOB = '000000010000000100000012004e0075006d004c00610079006500720073000000020000000000';
+
+function subtitleElement({ startFrame, durationFrames, text }) {
+  return (
+    `<Element>\n      <Sm2TiGenerator DbId="${crypto.randomUUID()}">\n` +
+    '       <FieldsBlob/>\n' +
+    '       <PrettyType>Subtitle</PrettyType>\n' +
+    `       <Name>${escapeXml(text)}</Name>\n` +
+    `       <Start>${startFrame}</Start>\n` +
+    `       <Duration>${durationFrames}</Duration>\n` +
+    '       <LinkedItemSync/>\n' +
+    '       <WasDisbanded>false</WasDisbanded>\n' +
+    '       <MarkersBA/>\n' +
+    '       <UiMemento>0</UiMemento>\n' +
+    '       <Flags>0</Flags>\n' +
+    '       <PriorityIndex>0</PriorityIndex>\n' +
+    '       <EffectFiltersBA/>\n' +
+    '       <ImportExportMetadataBA/>\n' +
+    '       <RenderTextEnabled>true</RenderTextEnabled>\n' +
+    '       <RenderTextGanged>true</RenderTextGanged>\n' +
+    '       <RenderTextPrefixed>true</RenderTextPrefixed>\n' +
+    '       <In/>\n' +
+    '      </Sm2TiGenerator>\n     </Element>'
+  );
+}
+
+/**
+ * Place subtitle cues on the (single) subtitle track of a timeline in a .drp.
+ * Overlapping cues are refused — one track cannot hold both.
+ *
+ * @param {Buffer|string} drpInput
+ * @param {object} opts
+ * @param {Array<{startFrame:number,durationFrames:number,text:string}>} opts.subtitles
+ *   startFrame is timeline-ABSOLUTE (origin 86400 on the bundled templates).
+ * @param {string} [opts.timelineUuid]
+ * @returns {Promise<{buffer:Buffer, entry:string, timelineUuid:string, count:number}>}
+ */
+async function placeSubtitles(drpInput, opts = {}) {
+  const { subtitles, timelineUuid } = opts;
+  if (!Array.isArray(subtitles) || !subtitles.length) throw new TypeError('placeSubtitles: subtitles must be a non-empty array');
+  const sorted = [...subtitles].sort((a, b) => a.startFrame - b.startFrame);
+  sorted.forEach((sub, i) => {
+    if (!Number.isInteger(sub.startFrame) || !Number.isInteger(sub.durationFrames) || sub.durationFrames <= 0) {
+      throw new TypeError(`placeSubtitles: subtitles[${i}] needs integer startFrame and positive durationFrames`);
+    }
+    if (typeof sub.text !== 'string' || !sub.text.length) throw new TypeError(`placeSubtitles: subtitles[${i}].text must be a non-empty string`);
+    if (i > 0 && sub.startFrame < sorted[i - 1].startFrame + sorted[i - 1].durationFrames) {
+      throw new RangeError(`placeSubtitles: cues ${i - 1} and ${i} overlap — one subtitle track cannot hold both`);
+    }
+  });
+
+  const zip = await loadDrpZip(drpInput);
+  const { entry, xml: seqXml, seqId } = await selectTargetSeq(zip, timelineUuid);
+  const seqUuidM = seqXml.match(/<Sequence>([0-9a-f-]{36})<\/Sequence>/);
+  if (!seqUuidM) throw new Error('placeSubtitles: cannot find the shared <Sequence> uuid');
+  const items = sorted.map(subtitleElement).join('\n     ');
+  const track =
+    `\n  <Element>\n   <Sm2TiTrack DbId="${crypto.randomUUID()}">\n` +
+    `    <FieldsBlob>${TRACK_FIELDS_BLOB}</FieldsBlob>\n` +
+    '    <Type>2</Type>\n    <SubType>0</SubType>\n    <Flags>0</Flags>\n' +
+    `    <Sequence>${seqUuidM[1]}</Sequence>\n` +
+    `    <Items>\n     ${items}\n    </Items>\n` +
+    '    <UserDefinedName/>\n    <LayersVec/>\n   </Sm2TiTrack>\n  </Element>\n ';
+  let xml;
+  if (/<SubtitleTrackVec\/>/.test(seqXml)) {
+    xml = seqXml.replace('<SubtitleTrackVec/>', `<SubtitleTrackVec>${track}</SubtitleTrackVec>`);
+  } else if (/<SubtitleTrackVec>/.test(seqXml)) {
+    xml = seqXml.replace('</SubtitleTrackVec>', `${track}</SubtitleTrackVec>`);
+  } else {
+    throw new Error('placeSubtitles: timeline has no SubtitleTrackVec');
+  }
+  zip.file(entry, xml);
+  const buffer = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  return { buffer, entry, timelineUuid: seqId, count: sorted.length };
+}
+
+/** Parse an SRT string → cues in frames at fps (timeline-RELATIVE, add the origin). */
+function parseSrt(srt, fps = 24) {
+  const cues = [];
+  const tc = (s) => {
+    const m = /(\d{2}):(\d{2}):(\d{2})[,.](\d{3})/.exec(s);
+    return Math.round(((+m[1] * 3600 + +m[2] * 60 + +m[3]) + +m[4] / 1000) * fps);
+  };
+  for (const block of String(srt).replace(/\r/g, '').split(/\n\n+/)) {
+    const lines = block.split('\n').filter((l) => l.trim().length);
+    const ti = lines.findIndex((l) => /-->/.test(l));
+    if (ti < 0) continue;
+    const [a, b] = lines[ti].split('-->');
+    const text = lines.slice(ti + 1).join('\n').trim();
+    if (!text) continue;
+    const start = tc(a), end = tc(b);
+    if (end > start) cues.push({ startFrame: start, durationFrames: end - start, text });
+  }
+  return cues;
+}
+
+module.exports = { placeSubtitles, parseSrt };

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.127.0"
+VERSION = "2.128.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.127.0"
+VERSION = "2.128.0"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -2033,7 +2033,12 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "the one shape where readback and render DIVERGE: the "
                    "item reads back frozen (source 96..96) but renders "
                    "MOVING (48/48 unique frames measured). Do not author "
-                   "freezes as flat timemaps.",
+                   "freezes as flat timemaps. AUDIO clips ignore the "
+                   "timemap entirely: a 50% keyed map on an imported audio "
+                   "clip reads back retimed (source 0..48 over 96 record "
+                   "frames) but RENDERS at 100% - unchanged pitch and "
+                   "spectrum (highpass/lowpass split identical to the 1x "
+                   "reference).",
         "recommended": "Author retimes for pre-21 hosts with the keyed "
                        "form (drt.assemble cuts[].speed does this; encoder "
                        "byte-exact against a live 19.1.3.7 harvest). Treat "