davinci-resolve-mcp 2.116.1 → 2.117.0

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

@@ -47,6 +47,7 @@ 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 |
 | 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.1"
+VERSION = "2.117.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.1",
+  "version": "2.117.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/README.md

@@ -102,8 +102,9 @@ Each dispatches on an `action`. Highlights:
   point across xml/edl/otio/drt/drp/aaf/prproj), `convert_to_interchange` (author OTIO/EDL/DRT that Resolve
   imports, from events or a parsed source — **the .prproj→Resolve conform bridge**, no Premiere needed;
   editorial timing/cuts/transitions carry, per-clip effects/color do not; speed/reverse carry on
-  the `otio` and `edl` targets only — `drt` has no per-clip speed field and reports every retime it
-  flattens in `flattened`),
+  the `otio` and `edl` targets only — this flat `drt` target has no per-clip speed field and reports
+  every retime it flattens in `flattened`; for a `.drt` that AUTHORS retimes (plus dissolves,
+  multi-track, audio) use `drt.assemble_from_interchange` instead),
   `turnover_changelist` (moved/retimed/replaced/new/gone + timing silent-lie guards), `conform_manifest`,
   `marker_roundtrip`.
 - **`provenance`** — provenance / audit: `gallery_lineage`, `grade_provenance` ("why is this graded this

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)}], 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/server/tools/editorial.mjs

@@ -86,7 +86,7 @@ const markerSchema = z.object({
 export const editorialTool = {
   name: 'editorial',
   description:
-    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively + AAF via pyaaf2 + PRPROJ via gunzip+XML → normalized events; for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — the DRT clip schema has no per-clip speed field, so target `drt` flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one; `flattened` is always present on `drt`, empty when there were none), turnover_changelist (diff old vs new → moved/retimed/replaced/new/gone + timing flags), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base), marker_roundtrip (markers with provenance tags). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
+    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively + AAF via pyaaf2 + PRPROJ via gunzip+XML → normalized events; for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → moved/retimed/replaced/new/gone + timing flags), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base), marker_roundtrip (markers with provenance tags). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
   async handler({ action, args }) {
     if (action === 'parse_interchange') {
       const p = parseSchema.parse(args);

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

@@ -33,6 +33,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 +66,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 +88,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 +192,28 @@ async function assembleTimeline(spec = {}) {
     }));
   }
 
-  return { buffer, timelineName: tlName, startFrame, mediaDescriptor: mediaDescriptorState };
+  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/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.116.1"
+VERSION = "2.117.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.1"
+VERSION = "2.117.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",