davinci-resolve-mcp 2.78.1 → 2.79.0

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.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 341-tool granular server instead
 """
 
-VERSION = "2.78.1"
+VERSION = "2.79.0"
 
 import base64
 import os
@@ -5999,7 +5999,10 @@ _PRPROJ_REFUSAL = (
     "advanced MCP — editorial.list_sequences / editorial.parse_interchange (format 'prproj'); "
     "(2) convert it to an importable interchange — editorial.convert_to_interchange "
     "(target 'otio'|'edl'|'drt') — then import that here with import_timeline_checked. "
-    "Editorial timing/cuts/transitions/speed carry over; per-clip effects/Lumetri color do not. "
+    "Editorial timing/cuts/transitions carry over; per-clip effects/Lumetri color do not. "
+    "Speed/reverse carry on 'otio' and 'edl' ONLY — the DRT clip schema has no per-clip "
+    "speed field, so 'drt' flattens every retime to 100% forward and reports them in "
+    "`flattened`. Prefer 'otio' or 'edl' for a cut that carries retimes. "
     "Alternatively export FCP7 XML / AAF / FCPXML from Premiere and conform that."
 )
 
@@ -6008,6 +6011,12 @@ _PRPROJ_REFUSAL = (
 # pool after import, not by rewriting the file.
 _BINARY_INTERCHANGE_EXTS = {".aaf"}
 
+# Interchange that is not XML at all. `.otio` is JSON, so the sanitize/relink pass —
+# which parses the file as XML and rewrites <pathurl> elements — cannot run on it, and
+# the missing-media / generator-clip advice it exists to give is not the diagnosis for
+# an .otio that fails to import.
+_JSON_INTERCHANGE_EXTS = {".otio"}
+
 
 def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
     path = p.get("path")
@@ -6018,12 +6027,50 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
     ext = os.path.splitext(path)[1].lower()
     if ext == ".prproj":
         return _err(_PRPROJ_REFUSAL, category="invalid_input")
+    # ImportTimelineFromFile silently no-ops on the never-saved default project: it returns
+    # nothing, creates no timeline, and reports no cause. The generic "Resolve created no
+    # timeline" error that came back instead sent people to source-clip resolution and
+    # sanitize_media — the wrong road entirely, because the file is fine.
+    #
+    # This is the last unrecorded member of a family the repo already documents: SaveProject
+    # returns False here (and blocks forever headless), CreateProject fails against a dirty
+    # untitled project, and DeleteProject's workaround warns against leaving the session on
+    # this fallback. Refusing early is what makes the cause visible.
+    #
+    # The refusal is HARD — no override flag. An override would reintroduce exactly the
+    # silent no-op this exists to kill, since the call cannot succeed either way.
+    #
+    # Resolve exposes no "is this project unsaved" predicate (no IsModified / IsSaved), so
+    # the test is the literal fallback name. Known hole, stated rather than hidden: a
+    # localized Resolve may not name it "Untitled Project", and this guard will miss it —
+    # such a session gets the old generic error, not a wrong answer.
+    from src.utils.project_cleanup import UNSAVED_DEFAULT_PROJECT
+    try:
+        _current_name = proj.GetName()
+    except Exception:
+        _current_name = None
+    if _current_name == UNSAVED_DEFAULT_PROJECT:
+        return _err(
+            f"Cannot import a timeline into the never-saved default project "
+            f"('{UNSAVED_DEFAULT_PROJECT}') — Resolve accepts the call and creates no "
+            f"timeline, with no error naming the cause.",
+            category="invalid_input",
+            remediation=(
+                "The project state is the problem, not the file. Save this project under a "
+                "name, or load an existing named project (project_manager.load), then retry "
+                "the import unchanged."
+            ),
+        )
     # AAF (and any binary interchange) is read natively by Resolve. The XML
     # sanitize/relink path parses the file as text, so it must be SKIPPED for AAF
     # even when sanitize_media / relink_search_roots is passed; fuzzy XML relink is
     # N/A (media links through the media pool). We still detect the created
     # (possibly offline) timeline via the before/after id diff.
     is_binary = ext in _BINARY_INTERCHANGE_EXTS
+    # .otio is JSON. The sanitize/relink pass parses the file as XML, so it cannot run here
+    # any more than it can on an AAF — and its advice (missing media, generator clips) is
+    # not the diagnosis for an .otio that fails to import.
+    is_json = ext in _JSON_INTERCHANGE_EXTS
     # sanitize_media (alias: relink_media) rewrites the XML to drop clipitems that
     # reference missing media or are generators (slug/solid w/ no pathurl) — both
     # abort Resolve's scripting-API import and leave the timeline fully offline.
@@ -6043,7 +6090,13 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
             "relinks via the media pool. Imported the file as-is; pass relink_search_roots to "
             "auto-relink after import."
         )
-    sanitize = sanitize_requested and not is_binary
+    elif is_json and (sanitize_requested or _binary_has_roots):
+        binary_relink_note = (
+            f"sanitize_media / XML path-rewrite relink are N/A for {ext} (JSON, not XML) — "
+            "imported as-is. Media links by the target_url recorded in the file; relink via "
+            "the media pool afterward (see `relink`)."
+        )
+    sanitize = sanitize_requested and not is_binary and not is_json
     if not sanitize and p.get("require_temp_path", True) and not _render_temp_path_ok(path):
         return _err(
             "path must be under the system temp directory unless require_temp_path=False",
@@ -6140,6 +6193,26 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
                     "Otherwise verify it exports/opens in Resolve directly, or convert to "
                     "FCP7 XML / FCPXML upstream and import that."
                 )
+            elif is_json:
+                # Measured on 19.1.3: Resolve DOES import OTIO through the scripting API —
+                # its own EXPORT_OTIO output re-imports cleanly. What it refuses is a
+                # document that is valid OTIO but not Resolve-shaped, and the shape it cares
+                # about most is the source frame ORIGIN: a clip's source_range must sit
+                # inside the media's real timecode range, so 0-based source offsets against
+                # media that starts at 01:00:00:00 produce no timeline at all. Missing media
+                # and sanitize_media are not the diagnosis here and pointing at them wastes
+                # the caller's time on a file whose media is online.
+                remediation = (
+                    f"Resolve created no timeline from this {ext}. This is usually the "
+                    "document's shape, not its media: Resolve expects Clip.2 with a "
+                    "media_references map, an available_range on each reference, and "
+                    "source_range frames expressed against the media's own timecode origin "
+                    "(0-based source offsets fail when the media does not start at "
+                    "00:00:00:00). Author it with editorial.convert_to_interchange "
+                    "(target 'otio'), supplying each event's media start timecode, and check "
+                    "the returned mediaOriginAssumed list. To compare against a known-good "
+                    "file, export any timeline with timeline.export EXPORT_OTIO."
+                )
             elif sanitize:
                 remediation = None
             else:
@@ -6180,6 +6253,9 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
             if is_binary:
                 msg += (" Relink via the media pool (right-click → Relink Clips) or point Resolve "
                         "at the media roots — AAF media links there, not by rewriting the file.")
+            elif is_json:
+                msg += (" Relink via the media pool — .otio is JSON, so sanitize_media cannot "
+                        "rewrite its paths; check each clip's target_url instead.")
             elif not sanitize:
                 msg += (" Retry with sanitize_media=True to drop missing-media/generator "
                         "clips so the remaining media links automatically.")