davinci-resolve-mcp 2.78.1 → 2.79.1

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

@@ -70,17 +70,32 @@ const downgradeSchema = z.object({
   appVersionString: z.string().optional().describe('DbAppVer comment to stamp (default derived from targetAppVersion, else "<v>.0.0.0000")'),
 });
 
+/**
+ * .drt/.drp are ZIP containers, so every reader here takes a FILE PATH. A caller reaching for the
+ * content-shaped convention its sibling text formats use (`{ content }`) otherwise gets a bare zod
+ * dump that never names the key it wanted.
+ */
+function requirePathArg(args, key, action) {
+  const a = args && typeof args === 'object' ? args : {};
+  if (typeof a[key] === 'string' && a[key]) return a;
+  const given = Object.keys(a).filter((k) => a[k] !== undefined);
+  throw new Error(
+    `drt.${action}: pass \`${key}\` — an absolute path to the .drt/.drp. A .drt/.drp is a ZIP container, so this action reads a FILE PATH, never file content` +
+      `${given.length ? ` (got: ${given.join(', ')})` : ' (got no arguments)'}.`,
+  );
+}
+
 export const drtTool = {
   name: 'drt',
   description:
     'DaVinci Resolve Timeline (.drt) operations — offline, no Resolve required. Actions: parse, list_sequences (enumerate the timelines inside a .drp/.drt → [{id,name,eventCount,index}] to drive a "which sequence?" picker), author, validate, inject_into_drp, extract_from_drp (pull one SeqContainer out as a .drt — feed the .drt to the Python davinci-resolve MCP timeline.import_timeline_checked, or use timeline.import_from_drp to do both), downgrade (stamp <ProjectVersion> down so an OLDER Resolve will import a .drt/.drp from a newer one — pass targetAppVersion like "19.1.3" or targetProjectVersion).',
   async handler({ action, args }) {
     if (action === 'parse') {
-      const p = parseSchema.parse(args);
+      const p = parseSchema.parse(requirePathArg(args, 'drtPath', 'parse'));
       return drt().parseDRT(p.drtPath);
     }
     if (action === 'list_sequences') {
-      const p = listSequencesSchema.parse(args);
+      const p = listSequencesSchema.parse(requirePathArg(args, 'drpPath', 'list_sequences'));
       const parsed = await drt().parseDRT(p.drpPath);
       const sequences = summarizeDrtTimelines(parsed);
       return { path: p.drpPath, count: sequences.length, sequences };
@@ -92,7 +107,7 @@ export const drtTool = {
       return { outputPath: p.outputPath, bytes: buf.length };
     }
     if (action === 'validate') {
-      const p = validateSchema.parse(args);
+      const p = validateSchema.parse(requirePathArg(args, 'drtPath', 'validate'));
       return drt().validateDRT(p.drtPath);
     }
     if (action === 'inject_into_drp') {

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

@@ -32,11 +32,15 @@ async function parseAnySource(sourcePath, sourceFormat) {
   return parseInterchange(fmt, content, {});
 }
 
+// drt/drp are accepted only so the caller gets parseInterchange's NAMED redirect to the
+// path-based reader instead of a bare enum-rejection that reads as "unsupported".
 const parseSchema = z.object({
-  format: z.enum(['edl', 'otio', 'xml', 'xmeml', 'fcp7', 'aaf', 'prproj']),
+  format: z.enum(['edl', 'otio', 'xml', 'xmeml', 'fcp7', 'aaf', 'prproj', 'drt', 'drp']),
   content: z
     .union([z.string(), z.object({}).passthrough()])
-    .describe('EDL text / OTIO JSON (string or object) / XMEML string. For AAF or PRPROJ (binary): the file PATH.'),
+    .describe(
+      'EDL text / OTIO JSON (string or object) / XMEML string. For AAF or PRPROJ (binary): the file PATH. For .drt/.drp (ZIP): use list_sequences or drt.parse — this action redirects.',
+    ),
   fps: z.number().optional(),
 });
 
@@ -82,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/speed survive, per-clip effects/color do not), 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 — 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).',
   async handler({ action, args }) {
     if (action === 'parse_interchange') {
       const p = parseSchema.parse(args);
@@ -125,6 +129,10 @@ export const editorialTool = {
         eventCount: events.length,
         ...(written || { content: authored.content }),
         ...(authored.spec ? { spec: authored.spec } : {}),
+        // skip-not-fake: the DRT clip schema has no per-clip speed field, so retimes cannot
+        // ride into a .drt. Name every event that lost one rather than returning a timeline
+        // the caller believes is conformed. Always present on 'drt' (empty = none to lose).
+        ...(authored.flattened ? { flattened: authored.flattened, flattenedCount: authored.flattened.length } : {}),
       };
     }
     if (action === 'turnover_changelist') {

package/resolve-advanced/vendor/conform-qc/packaging/emit-fcp7.js

@@ -6,6 +6,51 @@
  * NON-NEGOTIABLE #5: keep <in> and <pproTicksIn> CONSISTENT (Resolve reads the
  * ticks). We always emit ticks = sourceFrame * ticksPerFrame so a re-import
  * reproduces the same source frame. Round-trippable through parse/xmeml-geometry.
+ *
+ * Two importer contracts measured against Resolve 19.1.3, both of which fail SILENTLY
+ * — a clean-looking XML and a Resolve that does nothing:
+ *
+ *   1. <pathurl> must be percent-encoded PER SEGMENT. XML-escaping (&amp; &lt; &gt;) is
+ *      NOT URL-escaping; the two are different contracts and this file previously
+ *      applied only the first. Encoding the whole path in one pass would escape the '/'
+ *      separators too, so each segment is encoded and the separators are rejoined.
+ *      The Python side of this repo already got this right — see
+ *      src/utils/timeline_xml.py _disk_to_pathurl, which uses urllib.parse.quote
+ *      (safe='/' by default, i.e. the same per-segment behaviour).
+ *
+ *      What that actually costs you, measured on 19.1.3 one character at a time, each
+ *      as a raw pathurl vs the same path encoded, in a fresh project with an empty pool:
+ *
+ *          char      raw            encoded
+ *          space     links          links
+ *          #         links          links
+ *          %         NO TIMELINE    links
+ *          &         links          links
+ *          +         links          links
+ *          ?         links          links
+ *
+ *      So a raw space is survivable on this build — but a literal '%' is not: it makes
+ *      an invalid percent-escape, and Resolve rejects THE WHOLE IMPORT over it, not the
+ *      one clip, with no error. Encoding is what Resolve's own FCP7 exporter emits
+ *      (it writes Media%20Drive), it fixed the fatal case, and it broke none of the
+ *      other five — so encode, and do not rely on which characters happen to be
+ *      tolerated by the build in front of you.
+ *
+ *   2. The SEQUENCE needs its own <rate>. Without it Resolve creates no timeline at all —
+ *      not a partial one, not an offline one, nothing — however well-formed the clipitems
+ *      are. Measured by bisecting this emitter's output against Resolve's own FCP7 export
+ *      of the same cut: adding the sequence <rate> alone flipped the import from "no
+ *      timeline" to 2 items / 2 linked, and it was the ONLY element that did. <duration>
+ *      alone did not. The clipitem-level and file-level <duration>/<rate>/<enabled> that
+ *      Resolve's exporter writes turned out not to be required.
+ *
+ *   3. Every file def needs a <timecode> block MATCHING the media's embedded timecode.
+ *      Absent, zero, and wrong all silently reject THE ENTIRE IMPORT — not the one
+ *      clip. Every property you would naturally suspect (durations, pathurl form,
+ *      track count) is innocent. Because a wrong block is as fatal as no block, this
+ *      emitter never guesses one: it writes the block when the clip carries its media's
+ *      timecode and reports the clips that do not via fcp7TimecodeCoverage(), rather
+ *      than emitting a plausible 00:00:00:00 that kills the import.
  */
 
 const TPF_24 = 10584000000;
@@ -14,6 +59,104 @@ function esc(s) {
   return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
+/**
+ * A local path → a Premiere-style file URL, percent-encoded PER SEGMENT so the '/'
+ * separators survive. `encodeURIComponent` on the whole path would turn them into %2F.
+ */
+function pathToUrl(p) {
+  if (!p) return '';
+  return `file://localhost${String(p).split('/').map(encodeURIComponent).join('/')}`;
+}
+
+/** Frames dropped per drop-frame minute: 2 at 29.97, 4 at 59.94. */
+const dropPerMinute = (fps) => Math.round(Number(fps) / 30) * 2;
+
+/** "HH:MM:SS:FF" (or ";FF" for drop-frame) → absolute frame number. */
+function tcToFrames(tc, fps, drop) {
+  const m = String(tc).trim().match(/^(\d+):(\d{1,2}):(\d{1,2})[:;](\d{1,2})$/);
+  if (!m) return null;
+  const [hh, mm, ss, ff] = m.slice(1).map(Number);
+  const base = Math.max(1, Math.round(Number(fps) || 24));
+  const isDrop = drop != null ? Boolean(drop) : String(tc).includes(';');
+  let frames = ((hh * 3600 + mm * 60 + ss) * base) + ff;
+  if (isDrop) {
+    const totalMinutes = hh * 60 + mm;
+    frames -= dropPerMinute(fps) * (totalMinutes - Math.floor(totalMinutes / 10));
+  }
+  return frames;
+}
+
+/** Absolute frame number → "HH:MM:SS:FF" (";FF" when drop-frame). */
+function framesToTc(frame, fps, drop) {
+  const base = Math.max(1, Math.round(Number(fps) || 24));
+  const f = Math.max(0, Math.round(Number(frame) || 0));
+  const p2 = (n) => String(n).padStart(2, '0');
+  let minutes;
+  let rem;
+  if (drop) {
+    // Drop-frame counts SKIP labels, so the label is recovered by walking ten-minute
+    // blocks: the first minute of each block drops nothing, the other nine drop `d`.
+    const d = dropPerMinute(fps);
+    const perMin = base * 60 - d;
+    const perTenMin = perMin * 9 + base * 60;
+    minutes = Math.floor(f / perTenMin) * 10;
+    rem = f % perTenMin;
+    if (rem >= base * 60) {
+      rem -= base * 60;
+      minutes += 1 + Math.floor(rem / perMin);
+      rem = (rem % perMin) + d;
+    }
+  } else {
+    minutes = Math.floor(f / (base * 60));
+    rem = f % (base * 60);
+  }
+  const sep = drop ? ';' : ':';
+  return `${p2(Math.floor(minutes / 60))}:${p2(minutes % 60)}:${p2(Math.floor(rem / base))}${sep}${p2(rem % base)}`;
+}
+
+/**
+ * The media's embedded start timecode for a clip, as {frame, string, fps, drop} — or
+ * null when the clip does not carry it. Accepts either a timecode string (`startTc`)
+ * or an absolute frame (`startTcFrame`); when both are present the frame wins and the
+ * string is re-derived from it, so the two halves of the emitted block cannot disagree.
+ */
+function clipTimecode(c, seqFps) {
+  const fps = Number(c.startTcFps || c.srcFps || seqFps || 24);
+  const drop = Boolean(c.startTcDrop);
+  let frame = c.startTcFrame != null ? Math.round(Number(c.startTcFrame)) : null;
+  if (frame == null && c.startTc != null) frame = tcToFrames(c.startTc, fps, c.startTcDrop);
+  if (frame == null || !Number.isFinite(frame)) return null;
+  return { frame, string: framesToTc(frame, fps, drop), fps, drop };
+}
+
+/**
+ * Which clips will emit a <timecode> block and which will not. A clip missing its
+ * media's timecode is not a cosmetic gap: Resolve rejects the WHOLE import over a
+ * single absent block, so `missing` being non-empty means this XML will import nothing.
+ */
+function fcp7TimecodeCoverage(conformed) {
+  const seqFps = (conformed.sequence || {}).fps || 24;
+  const missing = [];
+  let withTimecode = 0;
+  (conformed.clips || []).forEach((c, i) => {
+    if (clipTimecode(c, seqFps)) withTimecode += 1;
+    else missing.push({ index: i, name: c.source_basename || '', path: c.path || '' });
+  });
+  return {
+    total: (conformed.clips || []).length,
+    withTimecode,
+    missing,
+    importable: missing.length === 0,
+  };
+}
+
+function timecodeBlock(tc, indent) {
+  return `\n${indent}<timecode><string>${tc.string}</string><frame>${tc.frame}</frame>`
+    + `<displayformat>${tc.drop ? 'DF' : 'NDF'}</displayformat>`
+    + `<rate><timebase>${Math.round(tc.fps)}</timebase><ntsc>${Number.isInteger(Number(tc.fps)) ? 'FALSE' : 'TRUE'}</ntsc></rate>`
+    + `</timecode>`;
+}
+
 function toFcp7Xml(conformed, opts = {}) {
   const seq = conformed.sequence || {};
   const tpf = conformed.ticksPerFrame || opts.ticksPerFrame || TPF_24;
@@ -28,7 +171,8 @@ function toFcp7Xml(conformed, opts = {}) {
       const ticksIn = inFrame * tpf; // CONSISTENT with <in>
       const ticksOut = (inFrame + dur) * tpf;
       const fileId = `file-${i + 1}`;
-      const url = c.path ? `file://localhost${esc(c.path)}` : '';
+      const url = pathToUrl(c.path);
+      const tc = clipTimecode(c, fps);
       return `      <clipitem id="clipitem-${i + 1}">
         <name>${esc(c.source_basename || `clip${c.seqstart}`)}</name>
         <start>${c.seqstart}</start>
@@ -37,7 +181,7 @@ function toFcp7Xml(conformed, opts = {}) {
         <out>${inFrame + dur}</out>
         <pproTicksIn>${ticksIn}</pproTicksIn>
         <pproTicksOut>${ticksOut}</pproTicksOut>
-        <file id="${fileId}"><name>${esc(c.source_basename || '')}</name><pathurl>${url}</pathurl>
+        <file id="${fileId}"><name>${esc(c.source_basename || '')}</name><pathurl>${url}</pathurl>${tc ? timecodeBlock(tc, '          ') : ''}
           <media><video><samplecharacteristics><width>${c.srcW || W}</width><height>${c.srcH || H}</height></samplecharacteristics></video></media>
         </file>
         <filter><effect><name>Basic Motion</name><effectid>basic</effectid>
@@ -47,10 +191,18 @@ function toFcp7Xml(conformed, opts = {}) {
     })
     .join('\n');
 
+  const seqDur = conformed.clips.reduce((m, c) => Math.max(m, c.seqend || c.seqstart || 0), 0);
+  const seqTc = clipTimecode({
+    startTc: seq.startTc, startTcFrame: seq.startTcFrame,
+    startTcFps: seq.startTcFps || fps, startTcDrop: seq.startTcDrop,
+  }, fps);
+
   return `<?xml version="1.0" encoding="UTF-8"?>
 <xmeml version="4">
 <sequence id="seq-conform">
   <name>${esc(seq.name || 'conform')}</name>
+  <duration>${seqDur}</duration>
+  <rate><timebase>${Math.round(fps)}</timebase><ntsc>${Number.isInteger(Number(fps)) ? 'FALSE' : 'TRUE'}</ntsc></rate>${seqTc ? timecodeBlock(seqTc, '  ') : ''}
   <media><video>
     <format><samplecharacteristics><rate><timebase>${fps}</timebase><ntsc>FALSE</ntsc></rate><width>${W}</width><height>${H}</height></samplecharacteristics></format>
     <track>
@@ -61,4 +213,4 @@ ${clipitems}
 </xmeml>`;
 }
 
-module.exports = { toFcp7Xml, TPF_24 };
+module.exports = { toFcp7Xml, fcp7TimecodeCoverage, pathToUrl, tcToFrames, framesToTc, TPF_24 };

package/resolve-advanced/vendor/conform-qc/packaging/index.js

@@ -13,7 +13,7 @@
 const fs = require('fs');
 const path = require('path');
 const { toOtio } = require('./otio');
-const { toFcp7Xml } = require('./emit-fcp7');
+const { toFcp7Xml, fcp7TimecodeCoverage } = require('./emit-fcp7');
 const { toAafModel } = require('./emit-aaf');
 
 const MEDIA_MODES = Object.freeze(['relink', 'full', 'consolidate']);
@@ -108,6 +108,9 @@ function buildPackage(conformed, opts = {}) {
   for (const f of formats) {
     if (f === 'otio') files.otio = toOtio(conformed);
     else if (f === 'fcp7Xml') files.fcp7Xml = toFcp7Xml(conformed, opts);
+    // A file def with no <timecode> makes Resolve reject THE WHOLE import, silently, so
+    // the coverage report rides with the package rather than being something the caller
+    // has to know to ask for. importable:false means this XML will import nothing.
     else if (f === 'aaf') files.aaf = toAafModel(conformed);
     else if (f === 'drp') files.drp = { blocked: true, reason: 'DRP authoring requires Resolve (Tier 3)' };
     else throw new Error(`package: unknown format "${f}"`);
@@ -115,6 +118,7 @@ function buildPackage(conformed, opts = {}) {
   const manifest = buildManifest(conformed, opts);
   const v2FlagTrack = opts.v2Flags || [];
   const pkg = { mediaMode, formats, files, media: buildMedia(conformed, mediaMode), v2FlagTrack, manifest };
+  if (files.fcp7Xml) pkg.fcp7Timecode = fcp7TimecodeCoverage(conformed);
   pkg.record = makeConformPackage({ mediaMode, formats, manifest, v2FlagCount: v2FlagTrack.length, version: opts.version, createdAt: opts.createdAt });
   return pkg;
 }

package/resolve-advanced/vendor/conform-qc/test/packaging.test.js

@@ -11,15 +11,21 @@ const path = require('node:path');
 const pkgRoot = require('../index');
 const P = require('../packaging');
 const { toOtio, readOtioSourceFrames } = require('../packaging/otio');
-const { toFcp7Xml } = require('../packaging/emit-fcp7');
+const { toFcp7Xml, fcp7TimecodeCoverage, pathToUrl, tcToFrames, framesToTc } = require('../packaging/emit-fcp7');
 const { toAafModel, readAafSourceFrames } = require('../packaging/emit-aaf');
 const { parseGeometry } = require('../parse');
 const oracle = require('../oracle');
 
-const GOLDEN = JSON.parse(fs.readFileSync(path.join(pkgRoot.reelFixtureDir(), 'golden_oracle.json'), 'utf8'));
+// The golden-answer reel is git-ignored client material (see index.js reelFixtureDir),
+// so on a fresh clone it is absent and the tests that need it SKIP. Loading it at module
+// scope made the whole file fail to load instead — which took the fixture-free tests
+// below down with it, and those are exactly the ones that pin the importer contracts.
+const GOLDEN_PATH = path.join(pkgRoot.reelFixtureDir(), 'golden_oracle.json');
+const GOLDEN = fs.existsSync(GOLDEN_PATH) ? JSON.parse(fs.readFileSync(GOLDEN_PATH, 'utf8')) : null;
+const needsGolden = { skip: GOLDEN ? false : 'golden reel fixture not present' };
 
 // A conformed timeline: each clip resolved to its source frame (= expected_source_start).
-const CONFORMED = {
+const CONFORMED = GOLDEN && {
   sequence: GOLDEN.sequence,
   ticksPerFrame: GOLDEN.ticksPerFrame,
   clips: GOLDEN.clips.map((c) => ({
@@ -35,16 +41,16 @@ const CONFORMED = {
     path: `/vol/online/${c.source_basename}`,
   })),
 };
-const CTX = { ticksPerFrame: GOLDEN.ticksPerFrame, sequenceWidth: GOLDEN.sequence.width };
+const CTX = GOLDEN && { ticksPerFrame: GOLDEN.ticksPerFrame, sequenceWidth: GOLDEN.sequence.width };
 
-test('package: OTIO canonical round-trips conformed source frames (all 327)', () => {
+test('package: OTIO canonical round-trips conformed source frames (all 327)', needsGolden, () => {
   const otio = toOtio(CONFORMED);
   const back = readOtioSourceFrames(otio);
   assert.equal(back.length, 327);
   for (let i = 0; i < back.length; i++) assert.equal(back[i].sourceFrame, CONFORMED.clips[i].sourceFrame);
 });
 
-test('package: FCP7 XML emit round-trips through the parser (in+ticks consistent, all 327)', () => {
+test('package: FCP7 XML emit round-trips through the parser (in+ticks consistent, all 327)', needsGolden, () => {
   const xml = toFcp7Xml(CONFORMED);
   const parsed = parseGeometry(xml);
   const bySeq = new Map(parsed.clips.map((c) => [c.seqstart, c]));
@@ -60,13 +66,13 @@ test('package: FCP7 XML emit round-trips through the parser (in+ticks consistent
   assert.equal(checked, 327);
 });
 
-test('package: AAF model round-trips source frames (binary serialization deferred)', () => {
+test('package: AAF model round-trips source frames (binary serialization deferred)', needsGolden, () => {
   const back = readAafSourceFrames(toAafModel(CONFORMED));
   assert.equal(back.length, 327);
   assert.equal(back[0].sourceFrame, CONFORMED.clips[0].sourceFrame);
 });
 
-test('package: builder matrix — subset of formats + relink media mode', () => {
+test('package: builder matrix — subset of formats + relink media mode', needsGolden, () => {
   const pkg = P.buildPackage(CONFORMED, { mediaMode: 'relink', formats: ['otio', 'fcp7Xml', 'aaf'] });
   assert.ok(pkg.files.otio && pkg.files.fcp7Xml && pkg.files.aaf);
   assert.equal(pkg.media.mode, 'relink');
@@ -74,12 +80,12 @@ test('package: builder matrix — subset of formats + relink media mode', () =>
   assert.ok(pkg.media.references.length === 327);
 });
 
-test('package: full/consolidate media modes are BLOCKED (require volumes)', () => {
+test('package: full/consolidate media modes are BLOCKED (require volumes)', needsGolden, () => {
   assert.equal(P.buildPackage(CONFORMED, { mediaMode: 'full' }).media.blocked, true);
   assert.equal(P.buildPackage(CONFORMED, { mediaMode: 'consolidate' }).media.blocked, true);
 });
 
-test('package: V2 flag track + provenance manifest + ConformPackage record', () => {
+test('package: V2 flag track + provenance manifest + ConformPackage record', needsGolden, () => {
   const v2Flags = [{ cutId: 'seq2983', klass: 'wrong-source', note: 'flagged' }];
   const repairByCut = { seq192: { strategy: 'add-subclip-startoffset', confidence: 1 } };
   const pkg = P.buildPackage(CONFORMED, { formats: ['otio'], v2Flags, repairByCut });
@@ -91,7 +97,7 @@ test('package: V2 flag track + provenance manifest + ConformPackage record', ()
   assert.equal(pkg.record.v2FlagCount, 1);
 });
 
-test('package: gated auto-apply applies only auto-apply fixes + records undo', () => {
+test('package: gated auto-apply applies only auto-apply fixes + records undo', needsGolden, () => {
   const small = { sequence: GOLDEN.sequence, ticksPerFrame: GOLDEN.ticksPerFrame, clips: [
     { cutId: 'a', seqstart: 0, sourceFrame: 100, scale: 175 },
     { cutId: 'b', seqstart: 48, sourceFrame: 200, scale: 175 },
@@ -108,7 +114,7 @@ test('package: gated auto-apply applies only auto-apply fixes + records undo', (
   assert.equal(out.deferred[0].cutId, 'b');
 });
 
-test('package: delivery to a local folder writes the files', () => {
+test('package: delivery to a local folder writes the files', needsGolden, () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cqc-pkg-'));
   try {
     const pkg = P.buildPackage(CONFORMED, { formats: ['otio', 'fcp7Xml'], v2Flags: [{ cutId: 'x' }] });
@@ -122,7 +128,7 @@ test('package: delivery to a local folder writes the files', () => {
   }
 });
 
-test('package: delivery to Download Center enqueues keys via injected sink (mock R2)', async () => {
+test('package: delivery to Download Center enqueues keys via injected sink (mock R2)', needsGolden, async () => {
   const uploaded = {};
   const enqueue = async (key, content) => { uploaded[key] = content; };
   const pkg = P.buildPackage(CONFORMED, { formats: ['otio'] });
@@ -131,3 +137,136 @@ test('package: delivery to Download Center enqueues keys via injected sink (mock
   assert.ok(keys.includes('conform/manifest.json'));
   assert.equal(Object.keys(uploaded).length, keys.length);
 });
+
+// ---------------------------------------------------------------------------
+// Resolve 19.1.3 importer contracts. Both failures are SILENT — a clean-looking
+// XML and a Resolve that does nothing — so they are pinned here rather than left
+// to be rediscovered. Fixture-free on purpose: these must run on a fresh clone.
+// ---------------------------------------------------------------------------
+
+// One clip whose media path has a space in two different segments, carrying an
+// embedded start timecode of 01:00:00:00 @ 24.
+const TC_CONFORMED = {
+  sequence: { name: 'tc', width: 1920, height: 1080, fps: 24 },
+  ticksPerFrame: 10584000000,
+  clips: [{
+    cutId: 'a',
+    seqstart: 0,
+    seqend: 48,
+    sourceFrame: 86400,
+    source_basename: 'take 01.mov',
+    path: '/Volumes/Media Drive/A Roll/take 01.mov',
+    startTc: '01:00:00:00',
+    startTcFps: 24,
+  }],
+};
+
+test('U7: pathurl is percent-encoded PER SEGMENT — %20 for spaces, / separators intact', () => {
+  // Measured on 19.1.3: a raw space survives, but a raw '%' is an invalid escape and
+  // kills THE WHOLE IMPORT. Encode everything rather than betting on the tolerated set.
+  assert.equal(
+    pathToUrl('/Volumes/Media Drive/A Roll/take 01.mov'),
+    'file://localhost/Volumes/Media%20Drive/A%20Roll/take%2001.mov',
+  );
+  // Encoding the path in ONE pass would have produced %2F separators — the bug that
+  // makes "just percent-encode it" fail differently instead of working.
+  assert.equal(pathToUrl('/a b/c d').includes('%2F'), false);
+  // The fatal one: a literal '%' must become %25, or the URL carries an invalid escape
+  // and Resolve creates no timeline at all.
+  assert.equal(pathToUrl('/vol/take%03.mov'), 'file://localhost/vol/take%2503.mov');
+
+  const xml = toFcp7Xml(TC_CONFORMED);
+  const url = xml.match(/<pathurl>([^<]*)<\/pathurl>/)[1];
+  assert.equal(url, 'file://localhost/Volumes/Media%20Drive/A%20Roll/take%2001.mov');
+  assert.equal(/<pathurl>[^<]* /.test(xml), false, 'no raw space survives inside a pathurl');
+});
+
+test('U8: every file def carries a <timecode> block MATCHING the media embedded TC', () => {
+  // Absent, zero, and wrong all silently reject THE ENTIRE IMPORT (measured, 19.1.3).
+  const xml = toFcp7Xml(TC_CONFORMED);
+  const block = xml.match(/<timecode>[\s\S]*?<\/timecode>/);
+  assert.ok(block, 'a file def with known media TC emits a <timecode> block');
+  assert.match(block[0], /<string>01:00:00:00<\/string>/);
+  assert.match(block[0], /<frame>86400<\/frame>/);   // 01:00:00:00 @ 24
+  assert.match(block[0], /<displayformat>NDF<\/displayformat>/);
+  assert.match(block[0], /<timebase>24<\/timebase>/);
+  // It lives INSIDE the <file> def, not at sequence level.
+  assert.match(xml, /<file id="file-1">[\s\S]*?<timecode>[\s\S]*?<\/timecode>[\s\S]*?<\/file>/);
+  // Not the zero block that reads as present and imports as nothing.
+  assert.equal(/<string>00:00:00:00<\/string>/.test(xml), false);
+});
+
+test('U8: startTcFrame and startTc agree; the frame wins and the string is re-derived', () => {
+  const byFrame = toFcp7Xml({ ...TC_CONFORMED, clips: [{ ...TC_CONFORMED.clips[0], startTc: undefined, startTcFrame: 86400 }] });
+  assert.match(byFrame, /<string>01:00:00:00<\/string>/);
+  assert.match(byFrame, /<frame>86400<\/frame>/);
+  // A disagreeing pair cannot emit a half-right block: the frame is authoritative.
+  const both = toFcp7Xml({ ...TC_CONFORMED, clips: [{ ...TC_CONFORMED.clips[0], startTc: '05:00:00:00', startTcFrame: 86400 }] });
+  assert.match(both, /<string>01:00:00:00<\/string>/);
+});
+
+test('U8: drop-frame media emits a DF block with the drop-frame frame count', () => {
+  const df = toFcp7Xml({
+    ...TC_CONFORMED,
+    clips: [{ ...TC_CONFORMED.clips[0], startTc: '01:00:00;00', startTcFps: 29.97, startTcDrop: true }],
+  });
+  assert.match(df, /<string>01:00:00;00<\/string>/);
+  assert.match(df, /<frame>107892<\/frame>/); // DF, not the 108000 an NDF count would give
+  assert.match(df, /<displayformat>DF<\/displayformat>/);
+  assert.match(df, /<ntsc>TRUE<\/ntsc>/);
+});
+
+test('U8: a clip with NO media timecode emits no block and is REPORTED, not guessed', () => {
+  // A wrong block is exactly as fatal as no block, so the emitter never invents one —
+  // it says which clips it could not write, and that the XML will import nothing.
+  const noTc = { ...TC_CONFORMED, clips: [{ ...TC_CONFORMED.clips[0], startTc: undefined, startTcFps: undefined }] };
+  const xml = toFcp7Xml(noTc);
+  assert.equal(/<timecode>/.test(xml), false);
+  const cov = fcp7TimecodeCoverage(noTc);
+  assert.equal(cov.total, 1);
+  assert.equal(cov.withTimecode, 0);
+  assert.equal(cov.importable, false);
+  assert.equal(cov.missing[0].name, 'take 01.mov');
+
+  const ok = fcp7TimecodeCoverage(TC_CONFORMED);
+  assert.equal(ok.withTimecode, 1);
+  assert.equal(ok.importable, true);
+  assert.deepEqual(ok.missing, []);
+});
+
+test('U8: buildPackage carries the timecode coverage alongside the fcp7 XML', () => {
+  const pkg = P.buildPackage(TC_CONFORMED, { formats: ['fcp7Xml'] });
+  assert.equal(pkg.fcp7Timecode.importable, true);
+  assert.equal(pkg.fcp7Timecode.withTimecode, 1);
+  // Not attached when no fcp7 XML was asked for.
+  assert.equal(P.buildPackage(TC_CONFORMED, { formats: ['otio'] }).fcp7Timecode, undefined);
+});
+
+test('U8: timecode <-> frame conversion is exact, non-drop and drop', () => {
+  for (const [tc, fps] of [['01:00:00:00', 24], ['00:59:50:00', 24], ['10:00:00:00', 25], ['23:59:59:23', 24]]) {
+    assert.equal(framesToTc(tcToFrames(tc, fps, false), fps, false), tc, `${tc} @${fps}`);
+  }
+  assert.equal(tcToFrames('01:00:00;00', 29.97, true), 107892);
+  assert.equal(tcToFrames('00:10:00;00', 29.97, true), 17982);
+  assert.equal(tcToFrames('00:01:00;02', 29.97, true), 1800);
+  for (const f of [0, 1800, 17981, 17982, 107892]) {
+    assert.equal(tcToFrames(framesToTc(f, 29.97, true), 29.97, true), f, `DF frame ${f}`);
+  }
+});
+
+test('emit: the SEQUENCE carries its own <rate> — without it Resolve creates no timeline', () => {
+  // Bisected against Resolve's own FCP7 export on 19.1.3: the sequence <rate> was the
+  // single element that flipped this emitter's output from "no timeline" to 2 items /
+  // 2 linked. <duration> alone did not, and the clipitem/file <duration>/<rate>/<enabled>
+  // that Resolve's exporter writes were not required.
+  const xml = toFcp7Xml(TC_CONFORMED);
+  const head = xml.slice(0, xml.indexOf('<media>'));
+  assert.match(head, /<rate><timebase>24<\/timebase><ntsc>FALSE<\/ntsc><\/rate>/);
+  assert.match(head, /<duration>48<\/duration>/);
+  // A sequence start timecode rides at sequence level when the caller supplies one.
+  const withTc = toFcp7Xml({ ...TC_CONFORMED, sequence: { ...TC_CONFORMED.sequence, startTc: '00:59:50:00' } });
+  assert.match(withTc.slice(0, withTc.indexOf('<media>')), /<string>00:59:50:00<\/string>/);
+  // 23.976 is the fractional case: NTSC must read TRUE, timebase must round to 24.
+  const ntsc = toFcp7Xml({ ...TC_CONFORMED, sequence: { ...TC_CONFORMED.sequence, fps: 23.976 } });
+  assert.match(ntsc.slice(0, ntsc.indexOf('<media>')), /<timebase>24<\/timebase><ntsc>TRUE<\/ntsc>/);
+});

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.78.1"
+VERSION = "2.79.1"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")