davinci-resolve-mcp 2.116.2 → 2.118.0

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

@@ -47,6 +47,8 @@ window. `render.verify_output` covers the container-level checks.
 | 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 |
+| Custom start timecode | `spec.startFrame` / `preserveStartTimecode` | v2.117 |
+| Timeline markers | `spec.markers` (16 colors, notes, durations, customData) | v2.118 |
 | 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

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 33 missing capabilities, 44 bugs / unreliable behaviors.
+**Totals:** 34 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
@@ -214,6 +214,13 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Treat as irreversible within a session. server returns _ok() unconditionally because there is nothing to check.
 - **Tags:** resolve-21, unreliable-return, irreversible, session-wide
 
+### A timeline's start timecode lives in the pool clip's MediaExtents blob (patchable offline)
+
+- **Object:** `Sm2MpTimelineClip.MediaExtents`
+- **Behavior:** The start timecode of a timeline is stored in exactly one non-cosmetic place in a .drp/.drt: the media pool timeline clip's MediaExtents blob, a 16-byte pair of LE doubles [startSeconds, durationSeconds] (measured: 02:03:04:05 @24 appears only as 7384.2083 there and in a UI-state blob). Patching startSeconds offline and importing yields a timeline at the new start timecode with clips at their absolute frames, and it renders.
+- **Workaround / current handling:** To author a non-default start TC offline, patch MediaExtents (drt.assemble spec.startFrame does this) and keep clip Start frames >= the new origin - clips before it are silently dropped on import. For conform, assemble_from_interchange preserveStartTimecode=true anchors at the turnover's real first record frame instead of 01:00:00:00.
+- **Tags:** timecode, drt, import
+
 ### MediaPool.ImportMedia (current-folder destination only)
 
 - **Object:** `MediaPool`

package/install.py

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

@@ -220,14 +220,14 @@ export function eventsToOTIO(events, opts = {}) {
  * @returns {{spec: object, report: object}}
  */
 export function eventsToAssembleSpec(events, opts = {}) {
-  const { sourceMap, timelineName } = opts;
+  const { sourceMap, timelineName, preserveStartTimecode = false } = opts;
   if (!Array.isArray(events) || !events.length) {
     throw new TypeError('eventsToAssembleSpec: events must be a non-empty array');
   }
   if (!sourceMap || typeof sourceMap !== 'object') {
     throw new TypeError('eventsToAssembleSpec: sourceMap {reel: {mediaFilePath, spec}} is required');
   }
-  const ORIGIN = 86400;
+  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 auds = events.filter((e) => isAudio(e.track) && e.recIn != null && e.recOut != null);
@@ -252,7 +252,15 @@ export function eventsToAssembleSpec(events, opts = {}) {
   const perSource = new Map();
   const placements = [];
 
-  const minRec = Math.min(...vids.map((e) => toTl(e.recIn, e.fps)));
+  // Default: anchor the earliest event at the template origin (86400).
+  // preserveStartTimecode keeps the interchange's ABSOLUTE record positions —
+  // the assembled timeline starts at the turnover's real first record frame
+  // (MediaExtents start-TC patch, measured: imports with the new start TC and
+  // renders). AAF conforms need this: build at THAT start, not 01:00:00:00.
+  const minRecRaw = Math.min(...vids.map((e) => toTl(e.recIn, e.fps)));
+  const minRec = preserveStartTimecode ? 0 : minRecRaw;
+  const ORIGIN = preserveStartTimecode ? 0 : DEFAULT_ORIGIN;
+  const startFrame = preserveStartTimecode ? minRecRaw : DEFAULT_ORIGIN;
   for (const e of vids) {
     const recIn = ORIGIN + (toTl(e.recIn, e.fps) - minRec);
     const recOut = ORIGIN + (toTl(e.recOut, e.fps) - minRec);
@@ -419,7 +427,7 @@ export function eventsToAssembleSpec(events, opts = {}) {
   }
 
   return {
-    spec: { timelineName, media, ...(transitions.length ? { transitions } : {}) },
+    spec: { timelineName, media, ...(preserveStartTimecode ? { startFrame } : {}), ...(transitions.length ? { transitions } : {}) },
     report: {
       videoEvents: vids.length,
       sources: media.length,
@@ -431,7 +439,7 @@ export function eventsToAssembleSpec(events, opts = {}) {
       authoredRetimes,
       authoredTransitions: transitions,
       droppedTransitions,
-      origin: ORIGIN,
+      origin: startFrame,
     },
   };
 }

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

@@ -41,12 +41,14 @@ const assembleFromInterchangeSchema = z.object({
   outputPath: z.string().describe('Where the importable .drt is written'),
   targetAppVersion: z.union([z.string(), z.number()]).optional()
     .describe("Host Resolve version, e.g. '19.1' for pre-21"),
+  preserveStartTimecode: z.boolean().optional()
+    .describe('Keep the interchange\'s ABSOLUTE record start: the assembled timeline starts at the turnover\'s real first record frame instead of 01:00:00:00 (start-TC patch render-verified on 19). AAF conforms should pass true.'),
 });
 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), 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()])
@@ -220,6 +222,7 @@ export const drtTool = {
       if (!events || !events.length) return { error: 'no events parsed from the interchange input' };
       const { spec, report } = eventsToAssembleSpec(events, {
         sourceMap: p.sourceMap, timelineName: p.timelineName,
+        preserveStartTimecode: p.preserveStartTimecode,
       });
       if (p.targetAppVersion !== undefined) {
         spec.templateVersion = parseFloat(p.targetAppVersion) >= 21 ? 21 : 19;

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');
@@ -33,6 +34,13 @@ const { placeTransition } = require('./place-transition');
 
 async function assembleTimeline(spec = {}) {
   const { timelineName, elements = [], transitions = [], media, templateVersion } = spec;
+  // Timeline start (frames @24). The start timecode lives in ONE place — the
+  // pool timeline clip's MediaExtents [startSeconds, durationSeconds]
+  // double-LE pair (measured: patching it imports with the new start TC and
+  // renders; no other non-cosmetic copy exists). Clips are absolute frames,
+  // so a custom origin just moves the guard.
+  const originFrame = spec.startFrame ?? DEFAULT_START_FRAME;
+  if (!Number.isInteger(originFrame) || originFrame < 0) throw new TypeError('assembleTimeline: spec.startFrame must be a non-negative integer');
   if (!Array.isArray(elements)) throw new TypeError('assembleTimeline: elements must be an array');
   if (!Array.isArray(transitions)) throw new TypeError('assembleTimeline: transitions must be an array');
 
@@ -59,9 +67,9 @@ async function assembleTimeline(spec = {}) {
     const validateCuts = (src, label) => {
       const mediaSpec = src.spec;
       (src.cuts || []).forEach((cut, i) => {
-        if (cut.startFrame < DEFAULT_START_FRAME) {
+        if (cut.startFrame < originFrame) {
           throw new RangeError(
-            `assembleTimeline: ${label}.cuts[${i}].startFrame ${cut.startFrame} is before the timeline origin ${DEFAULT_START_FRAME} — Resolve silently drops it on import`,
+            `assembleTimeline: ${label}.cuts[${i}].startFrame ${cut.startFrame} is before the timeline origin ${originFrame} — Resolve silently drops it on import`,
           );
         }
         if (mediaSpec && Number.isFinite(mediaSpec.frameCount) && Number.isFinite(mediaSpec.fps)) {
@@ -81,7 +89,7 @@ async function assembleTimeline(spec = {}) {
     base = await addMediaClip({
       mediaFile: sources[0].mediaFilePath, spec: sources[0].spec, timelineName, templateVersion,
     });
-    base.startFrame = DEFAULT_START_FRAME;
+    base.startFrame = originFrame;
 
     // Transplant/insert native pool elements BEFORE cutting, so each cut can
     // reference its source's MediaRef.
@@ -185,7 +193,55 @@ async function assembleTimeline(spec = {}) {
     }));
   }
 
-  return { buffer, timelineName: tlName, startFrame, mediaDescriptor: mediaDescriptorState };
+  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';
+    let mpF = await zipF.file(mpP).async('string');
+    const tlBlocks = mpF.match(/<Sm2MpTimelineClip[\s\S]*?<\/Sm2MpTimelineClip>/g) || [];
+    const tlBlock = tlBlocks.find((b) => b.includes(`<Name>${tlName}</Name>`)) || tlBlocks[0];
+    if (!tlBlock) throw new Error('assembleTimeline: timeline pool clip not found for startFrame patch');
+    const meM = tlBlock.match(/<MediaExtents>([0-9a-fA-F]*)<\/MediaExtents>/);
+    if (!meM) throw new Error('assembleTimeline: timeline pool clip has no MediaExtents to patch');
+    let maxEnd = originFrame;
+    const collect = (arr) => (arr || []).forEach((x) => { const e = (x.startFrame ?? 0) + (x.durationFrames ?? 0); if (e > maxEnd) maxEnd = e; });
+    (Array.isArray(media) ? media : media ? [media] : []).forEach((src) => collect(src.cuts));
+    collect(elements);
+    const me = Buffer.alloc(16);
+    me.writeDoubleLE(originFrame / 24, 0);
+    me.writeDoubleLE((maxEnd - originFrame) / 24, 8);
+    mpF = mpF.replace(tlBlock, tlBlock.replace(meM[0], `<MediaExtents>${me.toString('hex')}</MediaExtents>`));
+    zipF.file(mpP, mpF);
+    buffer = await zipF.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  }
+
+  return { buffer, timelineName: tlName, startFrame: originFrame, mediaDescriptor: mediaDescriptorState };
 }
 
 module.exports = { assembleTimeline };

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.116.2"
+VERSION = "2.118.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.116.2"
+VERSION = "2.118.0"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -1914,6 +1914,28 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "structural readback cannot see this class.",
         "tags": ["media-pool", "import", "render", "silent-failure", "readback"],
     },
+    {
+        "symbol": "A timeline's start timecode lives in the pool clip's MediaExtents blob (patchable offline)",
+        "object": "Sm2MpTimelineClip.MediaExtents",
+        "reality": "The start timecode of a timeline is stored in exactly "
+                   "one non-cosmetic place in a .drp/.drt: the media pool "
+                   "timeline clip's MediaExtents blob, a 16-byte pair of "
+                   "LE doubles [startSeconds, durationSeconds] (measured: "
+                   "02:03:04:05 @24 appears only as 7384.2083 there and in "
+                   "a UI-state blob). Patching startSeconds offline and "
+                   "importing yields a timeline at the new start timecode "
+                   "with clips at their absolute frames, and it renders.",
+        "recommended": "To author a non-default start TC offline, patch "
+                       "MediaExtents (drt.assemble spec.startFrame does "
+                       "this) and keep clip Start frames >= the new origin "
+                       "- clips before it are silently dropped on import. "
+                       "For conform, assemble_from_interchange "
+                       "preserveStartTimecode=true anchors at the "
+                       "turnover's real first record frame instead of "
+                       "01:00:00:00.",
+        "tags": ["timecode", "drt", "import"],
+        "submit": "missing",
+    },
     {
         "symbol": "Audio tracks cannot be grown in an imported timeline; Fairlight strips live in the pool Sm2Sequence.FieldsBlob",
         "object": "Sm2TiTrack (audio) / FLStudioModelBA",