davinci-resolve-mcp 2.117.0 → 2.119.0

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

@@ -48,6 +48,8 @@ window. `render.verify_output` covers the container-level checks.
 | Audio placements, A1–A8 | `cuts[].audioOnly + track` | v2.115 |
 | Built-in generators | `elements: [{type:'generator', generatorName}]` | v2.110 |
 | Custom start timecode | `spec.startFrame` / `preserveStartTimecode` | v2.117 |
+| Timeline markers | `spec.markers` (16 colors, notes, durations, customData) | v2.118 |
+| Turnover markers | EDL `* LOC:` locators + OTIO markers → authored | v2.119 |
 | Fusion titles | `elements: [{type:'title', text}]` — **21-gen hosts only** | v2.108 |
 
 `assemble_from_interchange` drives the same engine from an EDL / OTIO /

package/install.py

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

@@ -229,9 +229,11 @@ export function eventsToAssembleSpec(events, opts = {}) {
   }
   const DEFAULT_ORIGIN = 86400;
   const isAudio = (t) => /^A\d*$/.test(String(t || ''));
-  const vids = events.filter((e) => !isAudio(e.track) && e.recIn != null && e.recOut != null);
+  const isMarker = (t) => t === 'MARKER';
+  const vids = events.filter((e) => !isAudio(e.track) && !isMarker(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;
+  const markerEvents = events.filter((e) => isMarker(e.track) && e.recIn != null);
+  const audioSkipped = events.length - vids.length - auds.length - markerEvents.length;
   if (!vids.length) throw new Error('eventsToAssembleSpec: no video events with record ranges');
 
   const unmapped = [...new Set([...vids, ...auds].map((e) => e.source).filter((srcName) => !sourceMap[srcName]))];
@@ -426,12 +428,31 @@ export function eventsToAssembleSpec(events, opts = {}) {
     transitions.push({ track: c.track, atFrame: c.atFrame, durationFrames: c.durationFrames, trackType: 'audio' });
   }
 
+  // Turnover markers (EDL * LOC: locators, OTIO Marker objects) → authored
+  // timeline markers. Interchange colors map to the measured Resolve names;
+  // unknown colors fall back to Blue. Frames are timeline-absolute like cuts.
+  const COLOR_MAP = {
+    blue: 'Blue', cyan: 'Cyan', green: 'Green', yellow: 'Yellow', red: 'Red',
+    pink: 'Pink', purple: 'Purple', magenta: 'Fuchsia', fuchsia: 'Fuchsia',
+    rose: 'Rose', lavender: 'Lavender', sky: 'Sky', mint: 'Mint',
+    lemon: 'Lemon', sand: 'Sand', cocoa: 'Cocoa', cream: 'Cream',
+    orange: 'Sand', white: 'Cream', black: 'Cocoa',
+  };
+  const markers = markerEvents
+    .map((e) => ({
+      frame: ORIGIN + (toTl(e.recIn, e.fps) - minRec),
+      color: COLOR_MAP[String(e.color || '').toLowerCase()] || 'Blue',
+      ...(e.name ? { name: e.name } : {}),
+    }))
+    .filter((m) => m.frame >= (preserveStartTimecode ? startFrame : DEFAULT_ORIGIN));
+
   return {
-    spec: { timelineName, media, ...(preserveStartTimecode ? { startFrame } : {}), ...(transitions.length ? { transitions } : {}) },
+    spec: { timelineName, media, ...(preserveStartTimecode ? { startFrame } : {}), ...(markers.length ? { markers } : {}), ...(transitions.length ? { transitions } : {}) },
     report: {
       videoEvents: vids.length,
       sources: media.length,
       audioEventsSkipped: audioSkipped,
+      authoredMarkers: markers.length,
       authoredAudioEvents: audioPlacements.length,
       audioRetimesSkipped,
       upperTrackCutsVideoOnly: placements.filter((pl) => pl.track > 1).length,

package/resolve-advanced/server/editorial.mjs

@@ -49,6 +49,8 @@ function evt(o) {
   return {
     index: o.index ?? null,
     track: o.track || 'V',
+    ...(o.name !== undefined ? { name: o.name } : {}),
+    ...(o.color !== undefined ? { color: o.color } : {}),
     source: o.source || 'UNKNOWN',
     srcIn: o.srcIn ?? null,
     srcOut: o.srcOut ?? null,
@@ -83,6 +85,19 @@ export function parseEDL(text, opts = {}) {
       }
       continue;
     }
+    // Avid-style locators: `* LOC: 01:00:01:12 BLUE marker text` — a marker
+    // at an absolute record timecode. Emitted as track 'MARKER' pseudo-events
+    // (recIn only) so the assemble bridge can author them; consumers that
+    // filter video/audio by track shape ignore them.
+    const loc = /^\*\s*LOC:\s*(\d{2}:\d{2}:\d{2}[:;]\d{2})\s+(\S+)\s*(.*)$/i.exec(line);
+    if (loc) {
+      events.push(evt({
+        index: events.length + 1, track: 'MARKER', source: '',
+        recIn: tcToFrames(loc[1], fps), recOut: null,
+        name: loc[3].trim() || undefined, color: loc[2], fps,
+      }));
+      continue;
+    }
     const tokens = line.split(/\s+/);
     if (!/^\d+$/.test(tokens[0])) continue; // not an event line
     const tcs = tokens.filter(isTc);
@@ -147,6 +162,14 @@ export function parseOTIO(otio, opts = {}) {
           }
         }
         const src = (child.media_reference && (child.media_reference.target_url || child.media_reference.name)) || child.name || 'UNKNOWN';
+        for (const mk of child.markers || []) {
+          const mrStart = (mk.marked_range && mk.marked_range.start_time && mk.marked_range.start_time.value) || 0;
+          events.push(evt({
+            index: idx++, track: 'MARKER', source: '',
+            recIn: rec + (mrStart - startVal), recOut: null,
+            name: mk.name || undefined, color: mk.color || undefined, fps: rate,
+          }));
+        }
         events.push(
           evt({
             index: idx++,

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

@@ -48,7 +48,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)}], 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), 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

@@ -26,6 +26,7 @@ const { loadMediaTemplate, transplantMediaElement, insertMediaElement } = requir
 const JSZip = require('jszip');
 const { cutSourceIntoClips } = require('./cut-media');
 const { buildConstantSpeedTimemapKeyed } = require('./media-timemap');
+const { encodeTimelineMarkersBlob } = require('./timeline-markers-blob');
 const { randomUUID } = require('node:crypto');
 const { placeFusionTitle } = require('./place-fusion-title');
 const { placeGenerator } = require('./place-generator');
@@ -192,6 +193,33 @@ async function assembleTimeline(spec = {}) {
     }));
   }
 
+  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
+    // <Sequence> references). Encoder byte-exact vs a live 19.1.3.7 export.
+    // Marker frames here are TIMELINE-ABSOLUTE for consistency with cuts;
+    // the blob stores them start-relative.
+    const zipM = await JSZip.loadAsync(buffer);
+    const seqName = Object.keys(zipM.files).find((n) => !zipM.files[n].dir && /SeqContainer\/.+\.xml$/.test(n));
+    const seqXml2 = await zipM.file(seqName).async('string');
+    const seqIdM = (seqXml2.match(/<Sequence>([0-9a-f-]{36})<\/Sequence>/) || [])[1];
+    if (!seqIdM) throw new Error('assembleTimeline: cannot find the Sm2Sequence id for markers');
+    const rel = spec.markers.map((m) => {
+      if (!Number.isInteger(m.frame) || m.frame < originFrame) {
+        throw new RangeError(`assembleTimeline: marker frame ${m.frame} is before the timeline origin ${originFrame} (frames are timeline-absolute)`);
+      }
+      return { ...m, frame: m.frame - originFrame };
+    });
+    const blob = encodeTimelineMarkersBlob(rel);
+    let pjX = await zipM.file('project.xml').async('string');
+    const setM = pjX.match(/<LocableBlobSet>[\s\S]*?<\/LocableBlobSet>/);
+    if (!setM) throw new Error('assembleTimeline: project.xml has no LocableBlobSet to hold markers');
+    const el = `<Element>\n     <Sm2SequenceLockableBlob DbId="${randomUUID()}">\n      <FieldsBlob>${blob.toString('hex')}</FieldsBlob>\n      <BlobOwner>${seqIdM}</BlobOwner>\n      <DbSavedTime>0</DbSavedTime>\n     </Sm2SequenceLockableBlob>\n    </Element>\n   `;
+    pjX = pjX.replace('</LocableBlobSet>', `${el}</LocableBlobSet>`);
+    zipM.file('project.xml', pjX);
+    buffer = await zipM.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  }
+
   if (originFrame !== DEFAULT_START_FRAME) {
     const zipF = await JSZip.loadAsync(buffer);
     const mpP = 'MediaPool/Master/MpFolder.xml';

package/resolve-advanced/vendor/drp-format/marker-encoder.js

@@ -1,6 +1,12 @@
 /**
  * DaVinci Resolve Timeline Marker Encoder/Decoder
  *
+ * DEPRECATED for .drp/.drt authoring: this module's color map and emitted
+ * bytes never matched a real Resolve export (measured 2026-08-30 — Yellow is
+ * 16 not 8, Purple is 128, and the framing differs). Use
+ * timeline-markers-blob.js, whose encoder is byte-exact against a live
+ * 19.1.3.7 export and render/readback-verified through drt.assemble.
+ *
  * Encodes and decodes timeline markers into DaVinci Resolve's
  * compressed protobuf format stored in Sm2SequenceLockableBlob.FieldsBlob.
  *

package/resolve-advanced/vendor/drp-format/timeline-markers-blob.js

@@ -0,0 +1,159 @@
+/**
+ * timeline-markers-blob — encode/decode TIMELINE markers as the
+ * Sm2SequenceLockableBlob.FieldsBlob that lives in project.xml.
+ *
+ * Ground truth (harvested live from Studio 19.1.3.7, all 16 colors + custom
+ * data + durations, decoded round-trip against the API's own readback):
+ *
+ *   FieldsBlob = keyed-dict { "BlobData": bytes }
+ *   BlobData   = [u32BE 10001][u32BE innerLen][0x81][zstd frame]
+ *   zstd frame = magic 28b52ffd + single-segment header + RAW block(s)
+ *                (Resolve itself emits raw-block zstd for small payloads —
+ *                 accepted on import; no real compressor needed)
+ *   payload    = protobuf: field2 { repeated field1 MarkerEntry }
+ *   MarkerEntry= f1 varint frameRelative, f2 bytes {
+ *                  [u32BE 2][u32BE innerLen] f1 bytes {
+ *                    f1 varint colorBit,
+ *                    f3 string note, f3 string durationString, f3 string name,
+ *                    f6 string customData (present only when non-empty)
+ *                  } }
+ *
+ * Marker frames are RELATIVE to the timeline start (frame 0 = first frame),
+ * matching the scripting API's marker frame space. The blob attaches inside
+ * project.xml's <LocableBlobSet> (Resolve's own spelling) with
+ * <BlobOwner> = the timeline's Sm2Sequence DbId (the same uuid every track's
+ * <Sequence> references).
+ *
+ * Color bits (measured, one marker per color): sequential powers of two with
+ * 256 unassigned. This supersedes marker-encoder.js, whose map was wrong for
+ * Yellow/Purple/Lavender and whose emitted bytes never matched a real export.
+ *
+ * @module drp-format/timeline-markers-blob
+ */
+
+const { encodeKeyedDict, decodeKeyedDict } = require('./keyed-dict');
+
+const MARKER_COLOR_BITS = {
+  Blue: 2, Cyan: 4, Green: 8, Yellow: 16, Red: 32, Pink: 64, Purple: 128,
+  Fuchsia: 512, Rose: 1024, Lavender: 2048, Sky: 4096, Mint: 8192,
+  Lemon: 16384, Sand: 32768, Cocoa: 65536, Cream: 131072,
+};
+const BITS_TO_COLOR = Object.fromEntries(Object.entries(MARKER_COLOR_BITS).map(([k, v]) => [v, k]));
+
+function varint(n) {
+  const out = [];
+  let v = n >>> 0;
+  do { out.push((v & 0x7f) | (v > 0x7f ? 0x80 : 0)); v >>>= 7; } while (v);
+  return Buffer.from(out);
+}
+const lenDelim = (field, payload) => Buffer.concat([varint((field << 3) | 2), varint(payload.length), payload]);
+const varField = (field, n) => Buffer.concat([varint(field << 3), varint(n)]);
+
+function encodeMarkerEntry(m) {
+  const colorBit = MARKER_COLOR_BITS[m.color] ?? MARKER_COLOR_BITS.Blue;
+  const strs = [m.note ?? '', String(m.duration ?? 1), m.name ?? ''];
+  const body = Buffer.concat([
+    varField(1, colorBit),
+    ...strs.map((s) => lenDelim(3, Buffer.from(s, 'utf8'))),
+    ...(m.customData ? [lenDelim(6, Buffer.from(m.customData, 'utf8'))] : []),
+  ]);
+  const inner = lenDelim(1, body);
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(2, 0);
+  head.writeUInt32BE(inner.length, 4);
+  const wrapped = Buffer.concat([head, inner]);
+  return lenDelim(1, Buffer.concat([varField(1, m.frame), lenDelim(2, wrapped)]));
+}
+
+/** zstd single-segment frame with one RAW block (no compression). */
+function zstdRawFrame(payload) {
+  const magic = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+  let header;
+  if (payload.length <= 255) {
+    header = Buffer.from([0x20, payload.length]); // single-segment, 1-byte FCS
+  } else {
+    header = Buffer.alloc(5);
+    header[0] = 0xa0; // single-segment, 4-byte FCS
+    header.writeUInt32LE(payload.length, 1);
+  }
+  const block = Buffer.alloc(3);
+  block.writeUIntLE((payload.length << 3) | 1, 0, 3); // last=1, type=raw
+  return Buffer.concat([magic, header, block, payload]);
+}
+
+function zstdRawInflate(buf) {
+  if (buf.readUInt32LE(0) !== 0xfd2fb528) throw new Error('timeline-markers-blob: not a zstd frame');
+  const fhd = buf[4];
+  const single = (fhd >> 5) & 1;
+  const fcsCode = fhd >> 6;
+  let o = 5 + (single ? [1, 2, 4, 8][fcsCode] : [0, 2, 4, 8][fcsCode]);
+  if (fhd & 0x03) throw new Error('timeline-markers-blob: dictionary frames unsupported');
+  const out = [];
+  for (;;) {
+    const bh = buf.readUIntLE(o, 3); o += 3;
+    const last = bh & 1, type = (bh >> 1) & 3, size = bh >> 3;
+    if (type === 0) { out.push(buf.subarray(o, o + size)); o += size; }
+    else if (type === 1) { out.push(Buffer.alloc(size, buf[o])); o += 1; }
+    else throw new Error('timeline-markers-blob: compressed zstd block — use a real zstd decoder');
+    if (last) break;
+  }
+  return Buffer.concat(out);
+}
+
+/**
+ * Encode timeline markers → Sm2SequenceLockableBlob FieldsBlob buffer.
+ * @param {Array<{frame:number,color?:string,name?:string,note?:string,duration?:number,customData?:string}>} markers
+ *   frame is timeline-RELATIVE (0 = first frame of the timeline).
+ */
+function encodeTimelineMarkersBlob(markers) {
+  for (const m of markers) {
+    if (!Number.isInteger(m.frame) || m.frame < 0) throw new TypeError('encodeTimelineMarkersBlob: marker.frame must be a non-negative integer (timeline-relative)');
+    if (m.color && !MARKER_COLOR_BITS[m.color]) {
+      throw new Error(`encodeTimelineMarkersBlob: unknown color "${m.color}" (known: ${Object.keys(MARKER_COLOR_BITS).join(', ')})`);
+    }
+  }
+  const entries = [...markers].sort((a, b) => b.frame - a.frame).map(encodeMarkerEntry);
+  const pb = lenDelim(2, Buffer.concat(entries));
+  const frame = zstdRawFrame(pb);
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(10001, 0);
+  head.writeUInt32BE(frame.length + 1, 4);
+  const blobData = Buffer.concat([head, Buffer.from([0x81]), frame]);
+  return encodeKeyedDict({ hdr: 1, entries: [
+    { key: 'BlobData', type: 0x0c, subType: 0, value: blobData.toString('hex') },
+  ] });
+}
+
+/** Decode a Sm2SequenceLockableBlob FieldsBlob → markers (raw/RLE zstd only). */
+function decodeTimelineMarkersBlob(buf) {
+  const d = decodeKeyedDict(buf);
+  const bd = d.entries.find((e) => e.key === 'BlobData');
+  if (!bd) throw new Error('decodeTimelineMarkersBlob: no BlobData entry');
+  const val = Buffer.from(bd.value, 'hex');
+  if (val.readUInt32BE(0) !== 10001 || val[8] !== 0x81) throw new Error('decodeTimelineMarkersBlob: unexpected BlobData framing');
+  const pb = zstdRawInflate(val.subarray(9));
+  let o = 0;
+  const rv = () => { let v = 0, s = 0; for (;;) { const b = pb[o++]; v |= (b & 0x7f) << s; if (!(b & 0x80)) return v >>> 0; s += 7; } };
+  const markers = [];
+  if (pb[o] === 0x12) { o++; rv(); }
+  while (o < pb.length && pb[o] === 0x0a) {
+    o++; const el = rv(); const end = o + el;
+    const m = { frame: null, color: null, note: '', duration: 1, name: '', customData: '' };
+    if (pb[o] === 0x08) { o++; m.frame = rv(); }
+    if (pb[o] === 0x12) {
+      o++; rv(); o += 8;
+      if (pb[o] === 0x0a) { o++; rv(); }
+      if (pb[o] === 0x08) { o++; m.color = BITS_TO_COLOR[rv()] ?? null; }
+      const strs = [];
+      while (o < end && pb[o] === 0x1a) { o++; const sl = rv(); strs.push(pb.subarray(o, o + sl).toString('utf8')); o += sl; }
+      [m.note = '', , m.name = ''] = strs;
+      m.duration = parseInt(strs[1] ?? '1', 10) || 1;
+      if (o < end && pb[o] === 0x32) { o++; const sl = rv(); m.customData = pb.subarray(o, o + sl).toString('utf8'); o += sl; }
+    }
+    o = end;
+    markers.push(m);
+  }
+  return markers;
+}
+
+module.exports = { encodeTimelineMarkersBlob, decodeTimelineMarkersBlob, MARKER_COLOR_BITS };

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.117.0"
+VERSION = "2.119.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.117.0"
+VERSION = "2.119.0"
 
 import base64
 import os