npm - davinci-resolve-mcp - Versions diffs - 2.57.4 → 2.58.0 - Mend

davinci-resolve-mcp 2.57.4 → 2.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (328) hide show

package/resolve-advanced/vendor/drp-format/README.md ADDED Viewed

@@ -0,0 +1,116 @@
+# drp-format — offline DaVinci Resolve project authoring & editing
+Read, author, and edit **real, importable** DaVinci Resolve 21 projects (`.drp`) and timelines
+(`.drt`) as files — no Resolve required. Everything here is verified by a live round-trip
+(author/edit → `import_project` → `lint`/`clip_where` → re-export decode), not just self-parse.
+Background + the full schema map: `docs/design/drp-drx-drt-closeout-harness/knowledge/resolve21-schema-reconciliation.md`
+and `.../resolve-authoring-completion.md`.
+> **Key fact:** a `.drp`/`.drt` is a zip of `SeqContainer/<uuid>.xml` (+ `MpFolder.xml`, `project.xml`,
+> `Gallery.xml`). A clip's track is just which `<Sm2TiTrack>` it sits under. Source in-points live in
+> `<In>` (timeline frames). Resolve links media by the path **inside the Media Pool blob**, not the
+> timeline's `<MediaFilePath>`, and does **not** reconform on import — so cached specs must match.
+---
+## MCP actions
+### `drt` tool — timeline format
+| Action | Purpose |
+|---|---|
+| `parse` | `.drt`/`.drp` → `{ timelines, metadata }` (reads real Resolve exports) |
+| `author` | spec → `.drt` |
+| `validate` | structural check |
+| `inject_into_drp` / `extract_from_drp` | graft / pull a SeqContainer |
+### `drp` tool — project authoring + editing (all offline/local unless noted)
+**Author from scratch**
+| Action | What it does |
+|---|---|
+| `create_empty_project` | fresh `.drp`, one empty timeline → `{ buffer, startFrame: 86400 }` |
+| `assemble_timeline` | declarative spec `{ timelineName, elements:[{type:'title'\|'generator', track, startFrame, …}], transitions }` → importable project |
+| `add_media_clip` | one media clip from an arbitrary **h264** file: `{ mediaFile, spec:{width,height,frameCount,fps}, timelineName?, durationFrames? }` |
+**Place elements (track-targeted — the #74 bypass, offline)**
+| Action | What it does |
+|---|---|
+| `place_fusion_title` | Text+ on a chosen track. Options: `text, font, style, size, vJustify, hJustify, color:{r,g,b}`, `trackIndex`, `startFrame`, `durationFrames` |
+| `place_generator` | built-in generator (`generatorName`, e.g. "Solid Color") on a chosen track |
+| `place_transition` | cross-dissolve at an abutting cut (`track`, `atFrame`, `durationFrames`) — clips need handle media |
+**Edit in place (video or audio via `trackType`)**
+| Action | What it does |
+|---|---|
+| `move_clip` | relocate a clip to another track / new `toStart` |
+| `delete_clip` | remove a clip; `ripple` closes the gap on that track |
+| `trim_clip` | tail-trim `newDuration`; `ripple` shifts later clips |
+| `trim_clip_head` | head trim — advances the source `<In>`; `ripple` keeps Start |
+| `split_clip` | razor at `atFrame` → two source-continuous clips |
+| `ripple_timeline` | cross-track ripple — shift all clips ≥ `at` by `delta` (video+audio, keeps sync) |
+**Media (conform / relink)**
+| Action | What it does |
+|---|---|
+| `relink_media` | repoint media paths in the Media Pool blobs + plain text (`mappings:[{from,to}]`) |
+| `repoint_media` | relink **+ fix cached specs** (res/frames/fps) for a differently-formatted file (`{from,to,fromSpec,toSpec}`) |
+**Grades + analysis (server/local)**
+| Action | What it does |
+|---|---|
+| `inject_grades` | apply DRX grades into a `.drp` |
+| `extract_node_graphs` | pull per-clip grade `<Body>` blobs as DRX envelopes |
+| `diff` | structural diff of two `.drp`s |
+| `validate` / `validate_async` / `status` | DRP validation (server) |
+> Clip selectors on the edit ops: `clipIndex` (0-based), `clipDbId`, or `nameContains`.
+---
+## Library functions (`require('drp-format')`)
+Same surface as the MCP actions, returning `{ buffer, … }`:
+`createEmptyProject`, `assembleTimeline`, `addMediaClip`, `placeFusionTitle`, `placeGenerator`,
+`placeTransition`, `moveClip`, `deleteClip`, `trimClip`, `trimClipHead`, `splitClip`, `rippleTimeline`,
+`relinkMedia`, `repointMedia`, `injectGrades`, `diff`.
+Title text/style codec: `decodeTitleInputs`, `setTitleInputs`, `decodeTitleText`, `setTitleText`.
+Shared surgery primitives: `seq-surgery.js`. Title-comp codec: `composition-text.js`.
+Plus the full **DRX grade** surface (`createSimpleGrade`, curves/qualifiers/windows/node-tree encoders).
+`drt-format` re-exports the timeline-only surface: `parseDRT`, `buildDRT`, `validateDRT`.
+---
+## Live-edit recipe (the one thing that needs Resolve running)
+**#74 — insert a Text+/generator on a chosen track of the OPEN timeline.** The API's
+`InsertFusionTitleIntoTimeline` takes no track arg (always the lowest unlocked video track). Bypass:
+via computer-use, **lock the video tracks below your target**, then call `timeline.insert_fusion_title` —
+it lands on the chosen track. Verified live. (For export-based workflows, `place_fusion_title` does this
+offline.)
+---
+## What's mapped (honest scope)
+**Fully mapped (read + write, round-trips byte-for-byte):** project packaging; tracks
+(`Sm2TiTrack`+Type+Sequence); clips; source in-points (`<In>`); Fusion titles
+(text/font/style/size/justify/color); generators; transitions; markers; grades (full DRX body);
+media path + resolution + frame-count + fps. **Plus the full Media-Pool metadata layer:** the
+keyed-dict format (`Geometry`/`Time`/`VideoMetadata`/`Proxy`/audio/small `FieldsBlob`) with typed
+values (`keyed-dict.js`); audio config (`TracksBA`/`VirtualAudioTrackBA` → sample-rate/channels/codec
+via `readAudioTracks`); the protobuf blobs `Radiometry` + transition/generator `EffectFiltersBA`
+(wire-level, `protobuf-wire.js`); and `MediaTimemapBA` retime — both the 1× compact form and the
+retimed `Sm2TimeMap` keyed-dict, including **dynamic/variable-speed ramps** (KeyframesBA = repeated
+`(record,source)` points; per-segment speed = Δsource/Δrecord), decoded *and* authorable
+(`media-timemap.js`, `buildConstantSpeedTimemap` / `buildTimemap`).
+**Carried verbatim (cloned, not byte-decoded — Resolve accepts, never authored):** zstd-compressed
+internal-state/cache `FieldsBlob`s (`classifyBlob` flags them; Node has no built-in zstd); the
+protobuf blobs' *field names* (wire structure is decoded; names need Resolve's private `.proto`); the
+Fusion comp beyond the title inputs we edit.
+**Limit:** media authoring is h264-only (cross-codec needs a per-codec template).

package/resolve-advanced/vendor/drp-format/__tests__/_resolve-verify.js ADDED Viewed

@@ -0,0 +1,39 @@
+/**
+ * RESOLVE_VERIFY helper.
+ *
+ * Test files that include Resolve-in-loop assertions (apply DRX via
+ * davinci-resolve-mcp, frame-compare via export_frame_as_still, etc.)
+ * gate themselves with this helper so CI environments without Resolve
+ * don't fail spuriously, and local sessions can opt-in by setting
+ * RESOLVE_VERIFY=1.
+ *
+ * Usage:
+ *   const test = require('node:test');
+ *   const { resolveVerifyTest } = require('./_resolve-verify');
+ *   resolveVerifyTest('apply DRX matches direct render', async () => {
+ *     // ... uses davinci-resolve-mcp via stdio ...
+ *   });
+ *
+ * When RESOLVE_VERIFY is set to '1' or 'true', the test runs
+ * normally. Otherwise it's marked skip with a clear reason.
+ */
+const test = require('node:test');
+function isResolveVerifyEnabled() {
+  const v = process.env.RESOLVE_VERIFY;
+  return v === '1' || v === 'true' || v === 'yes';
+}
+function resolveVerifyTest(name, fn) {
+  if (!isResolveVerifyEnabled()) {
+    test.skip(`${name} (skipped — set RESOLVE_VERIFY=1 to enable)`, () => {});
+    return;
+  }
+  test(name, fn);
+}
+module.exports = {
+  isResolveVerifyEnabled,
+  resolveVerifyTest,
+};

package/resolve-advanced/vendor/drp-format/__tests__/add-media-clip.test.js ADDED Viewed

@@ -0,0 +1,30 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const { addMediaClip } = require('../author-project');
+const { parseDRT } = require('../../drt-format');
+test('addMediaClip authors a project with the target media + patched specs', async () => {
+  const { buffer, timelineName, mediaFile } = await addMediaClip({
+    mediaFile: '/media/Sample Montage.mp4',
+    spec: { width: 1280, height: 960, frameCount: 3094, fps: 30000 / 1001 },
+    timelineName: 'Authored Cut', durationFrames: 240,
+  });
+  assert.strictEqual(timelineName, 'Authored Cut');
+  const parsed = await parseDRT(buffer);
+  const clip = parsed.timelines[0].videoTracks[0].clips[0];
+  assert.ok(clip.mediaFilePath.includes('Sample Montage.mp4'), 'clip points at target file');
+  assert.strictEqual(clip.duration, 240, 'clip trimmed to durationFrames');
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(buffer);
+  const mp = await zip.file('MediaPool/Master/MpFolder.xml').async('string');
+  assert.ok(mp.includes('<Name>Authored Cut</Name>'), 'timeline renamed');
+  assert.ok(mp.includes('<Name>Sample Montage.mp4</Name>'), 'media entry renamed');
+  const geo = Buffer.from(mp.match(/<Geometry>([0-9a-fA-F]+)<\/Geometry>/)[1], 'hex');
+  assert.ok(geo.includes(Buffer.from([0, 0, 5, 0])), 'width 1280 patched');  // 1280 = 0x500
+});
+test('addMediaClip validates inputs', async () => {
+  await assert.rejects(() => addMediaClip({ mediaFile: 'rel.mov', spec: { width: 1, height: 1, frameCount: 1, fps: 24 } }), /absolute/);
+  await assert.rejects(() => addMediaClip({ mediaFile: '/a/b.mov', spec: { width: 1 } }), /spec must/);
+});

package/resolve-advanced/vendor/drp-format/__tests__/assemble-timeline.test.js ADDED Viewed

@@ -0,0 +1,68 @@
+// Unit: assemble a full timeline from a declarative spec (composes the verified primitives).
+// Live Resolve round-trip is the acceptance gate.
+const test = require('node:test');
+const assert = require('node:assert');
+const { assembleTimeline } = require('../assemble-timeline');
+const { decodeTitleInputs } = require('../composition-text');
+const { parseDRT } = require('../../drt-format');
+async function compositionTexts(buffer) {
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(buffer);
+  const out = [];
+  for (const n of Object.keys(zip.files)) {
+    if (!/SeqContainer\/[^/]+\.xml$|SeqContainer\d*\.xml$/.test(n)) continue;
+    const x = await zip.files[n].async('string');
+    for (const tag of x.match(/<CompositionBA>[0-9a-fA-F]+<\/CompositionBA>/g) || []) {
+      out.push(decodeTitleInputs(tag.replace(/<\/?CompositionBA>/g, '')));
+    }
+  }
+  return out;
+}
+test('assembleTimeline composes a title (V2) + generator (V3) from a spec', async () => {
+  const start = 86400;
+  const { buffer, timelineName, startFrame } = await assembleTimeline({
+    timelineName: 'Assembled',
+    elements: [
+      { type: 'generator', generatorName: 'Solid Color', track: 3, startFrame: start, durationFrames: 120 },
+      { type: 'title', track: 2, startFrame: start, durationFrames: 120, text: 'HELLO', color: { r: 0.2, g: 0.8, b: 1 } },
+    ],
+  });
+  assert.strictEqual(timelineName, 'Assembled');
+  assert.strictEqual(startFrame, 86400);
+  const parsed = await parseDRT(buffer);
+  const tl = parsed.timelines[0];
+  assert.ok(tl.videoTracks.length >= 3, 'V1/V2/V3 present');
+  const titles = await compositionTexts(buffer);
+  const t = titles.find((x) => x.text === 'HELLO');
+  assert.ok(t, 'title text composed');
+  assert.deepStrictEqual(t.color, { r: 0.2, g: 0.8, b: 1 }, 'title color composed');
+});
+test('assembleTimeline places two abutting generators + a transition between them', async () => {
+  const s = 86400;
+  const { buffer } = await assembleTimeline({
+    timelineName: 'GenTrans',
+    elements: [
+      { type: 'generator', track: 1, startFrame: s, durationFrames: 100 },
+      { type: 'generator', track: 1, startFrame: s + 100, durationFrames: 100 },
+    ],
+    transitions: [{ track: 1, atFrame: s + 100, durationFrames: 24 }],
+  });
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(buffer);
+  let body = '';
+  for (const n of Object.keys(zip.files)) {
+    if (!/SeqContainer\/[^/]+\.xml$/.test(n)) continue;
+    body = await zip.files[n].async('string');
+  }
+  assert.ok(/<Sm2TiTransition\b/.test(body), 'transition composed between the generators');
+});
+test('assembleTimeline rejects unknown element types', async () => {
+  await assert.rejects(() => assembleTimeline({ elements: [{ type: 'bogus', track: 1, startFrame: 86400 }] }), /unknown type/);
+});

package/resolve-advanced/vendor/drp-format/__tests__/author-project.test.js ADDED Viewed

@@ -0,0 +1,57 @@
+// Unit: create a fresh importable project from scratch, then populate it.
+// Live Resolve round-trip is the acceptance gate (proven manually — see
+// resolve21-schema-reconciliation.md).
+const test = require('node:test');
+const assert = require('node:assert');
+const { createEmptyProject } = require('../author-project');
+const { placeFusionTitle } = require('../place-fusion-title');
+const { decodeTitleText } = require('../composition-text');
+const { parseDRT } = require('../../drt-format');
+test('createEmptyProject returns an importable empty timeline', async () => {
+  const { buffer, timelineName } = await createEmptyProject();
+  assert.strictEqual(timelineName, 'Timeline 1');
+  const parsed = await parseDRT(buffer);
+  assert.strictEqual(parsed.timelines.length, 1, 'one timeline');
+  const tl = parsed.timelines[0];
+  assert.ok((tl.videoTracks || []).length >= 1, 'has a video track');
+  assert.strictEqual((tl.videoTracks[0].clips || []).length, 0, 'timeline is empty');
+});
+test('createEmptyProject renames the timeline', async () => {
+  const { buffer } = await createEmptyProject({ timelineName: 'My Fresh Cut' });
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(buffer);
+  const mp = await zip.file('MediaPool/Master/MpFolder.xml').async('string');
+  assert.ok(mp.includes('<Name>My Fresh Cut</Name>'), 'renamed in media pool');
+  assert.ok(!mp.includes('<Name>Timeline 1</Name>'), 'default name gone');
+});
+test('createEmptyProject rejects angle brackets in the name', async () => {
+  await assert.rejects(() => createEmptyProject({ timelineName: 'bad<name>' }), /< or >/);
+});
+test('from scratch: createEmptyProject -> placeFusionTitle on V2 with text', async () => {
+  const { buffer, startFrame } = await createEmptyProject({ timelineName: 'Scratch' });
+  assert.strictEqual(startFrame, 86400, 'timeline origin exposed for correct clip placement');
+  const res = await placeFusionTitle(buffer, { trackIndex: 2, startFrame, durationFrames: 120, text: 'FROM SCRATCH' });
+  // The placed title is on V2 with the requested text.
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(res.buffer);
+  let text = null;
+  for (const n of Object.keys(zip.files)) {
+    if (!/SeqContainer\/[^/]+\.xml$|SeqContainer\d*\.xml$/.test(n)) continue;
+    const xml = await zip.files[n].async('string');
+    for (const tag of xml.match(/<CompositionBA>[0-9a-fA-F]+<\/CompositionBA>/g) || []) {
+      const t = decodeTitleText(tag.replace(/<\/?CompositionBA>/g, ''));
+      if (t === 'FROM SCRATCH') text = t;
+    }
+  }
+  assert.strictEqual(text, 'FROM SCRATCH', 'title text present');
+  const parsed = await parseDRT(res.buffer);
+  const tl = parsed.timelines.find((t2) => (t2.videoTracks || []).length >= 2);
+  assert.ok(tl, 'V2 exists');
+  assert.strictEqual(tl.videoTracks[1].clips.length, 1, 'title on V2');
+});

package/resolve-advanced/vendor/drp-format/__tests__/composition-text.test.js ADDED Viewed

@@ -0,0 +1,98 @@
+// Unit: read/replace a Fusion Title's on-screen text in a CompositionBA blob.
+// Encoding verified by live Resolve 21 import + re-export (the re-export reads back the
+// edited StyledText) — see resolve21-schema-reconciliation.md.
+const test = require('node:test');
+const assert = require('node:assert');
+const path = require('node:path');
+const fs = require('node:fs');
+const { decodeTitleText, setTitleText } = require('../composition-text');
+const { placeFusionTitle } = require('../place-fusion-title');
+const { parseDRT } = require('../../drt-format');
+const TEMPLATE = fs.readFileSync(path.join(__dirname, '..', 'templates', 'fusion-title.xml'), 'utf8');
+const TEMPLATE_BA = TEMPLATE.match(/<CompositionBA>([0-9a-fA-F]*)<\/CompositionBA>/)[1];
+const FIXTURE = path.resolve(
+  __dirname,
+  '../../../docs/design/drp-drx-drt-closeout-harness/fixtures/canary-resolve21.drp',
+);
+test('decodeTitleText reads the bundled template text', () => {
+  assert.strictEqual(decodeTitleText(TEMPLATE_BA), 'Custom Title');
+});
+test('setTitleText round-trips through decodeTitleText', () => {
+  const enc = setTitleText(TEMPLATE_BA, 'SAMPLE TITLE');
+  assert.strictEqual(decodeTitleText(enc), 'SAMPLE TITLE');
+  // idempotent re-edit
+  assert.strictEqual(decodeTitleText(setTitleText(enc, 'Second Edit 2')), 'Second Edit 2');
+});
+test('setTitleText round-trips text with quotes, backslashes, and newlines (Lua escaping)', () => {
+  for (const s of ['He said "hi"', 'back\\slash', 'line1\nline2', 'mix: "a"\\b\tc', 'price $5 & up']) {
+    const enc = setTitleText(TEMPLATE_BA, s);
+    assert.strictEqual(decodeTitleText(enc), s, `round-trip failed for ${JSON.stringify(s)}`);
+  }
+});
+test('placeFusionTitle honors the text option (CompositionBA rewritten in place)', async (t) => {
+  if (!fs.existsSync(FIXTURE)) { t.skip(`fixture missing: ${FIXTURE}`); return; }
+  const res = await placeFusionTitle(FIXTURE, { trackIndex: 2, startFrame: 1000, text: 'HELLO WORLD' });
+  // Re-read the placed clip's CompositionBA from the output zip and confirm the text.
+  const JSZip = require('jszip');
+  const zip = await JSZip.loadAsync(res.buffer);
+  let found = null;
+  for (const name of Object.keys(zip.files)) {
+    if (!/SeqContainer\/[^/]+\.xml$|SeqContainer\d*\.xml$/.test(name)) continue;
+    const xml = await zip.files[name].async('string');
+    for (const tag of xml.match(/<CompositionBA>[0-9a-fA-F]+<\/CompositionBA>/g) || []) {
+      const ba = tag.replace(/<\/?CompositionBA>/g, '');
+      const txt = decodeTitleText(ba);
+      if (txt === 'HELLO WORLD') found = txt;
+    }
+  }
+  assert.strictEqual(found, 'HELLO WORLD', 'placed title carries the requested on-screen text');
+  // And it still parses as a clip on V2.
+  const parsed = await parseDRT(res.buffer);
+  const tl = parsed.timelines.find((t2) => (t2.videoTracks || []).length >= 2 && t2.videoTracks[1].clips?.length === 1);
+  assert.ok(tl, 'title present on V2');
+});
+const { setTitleInputs, decodeTitleInputs } = require('../composition-text');
+test('setTitleInputs sets font/style/size/justify and round-trips', () => {
+  const enc = setTitleInputs(TEMPLATE_BA, { text: 'STYLED', font: 'Helvetica Neue', style: 'Bold', size: 0.14, hJustify: 0, vJustify: 1 });
+  const got = decodeTitleInputs(enc);
+  assert.strictEqual(got.text, 'STYLED');
+  assert.strictEqual(got.font, 'Helvetica Neue');
+  assert.strictEqual(got.style, 'Bold');
+  assert.strictEqual(got.size, 0.14);
+  assert.strictEqual(got.hJustify, 0);
+  assert.strictEqual(got.vJustify, 1);
+});
+test('decodeTitleInputs reads template defaults', () => {
+  const got = decodeTitleInputs(TEMPLATE_BA);
+  assert.strictEqual(got.text, 'Custom Title');
+  assert.strictEqual(got.font, 'Open Sans');
+  assert.strictEqual(typeof got.size, 'number');
+});
+test('setTitleInputs rejects unknown inputs', () => {
+  assert.throws(() => setTitleInputs(TEMPLATE_BA, { bogus: 1 }), /unknown input/);
+});
+test('setTitleInputs injects + round-trips text color (Red1/Green1/Blue1)', () => {
+  const enc = setTitleInputs(TEMPLATE_BA, { text: 'COLORED', color: { r: 0.9, g: 0.1, b: 0.2 } });
+  const got = decodeTitleInputs(enc);
+  assert.strictEqual(got.text, 'COLORED');
+  assert.deepStrictEqual(got.color, { r: 0.9, g: 0.1, b: 0.2 });
+  // re-setting replaces in place (no duplicate injection)
+  const enc2 = setTitleInputs(enc, { color: { r: 0.3 } });
+  assert.strictEqual(decodeTitleInputs(enc2).color.r, 0.3);
+});
+test('setTitleInputs rejects out-of-range color', () => {
+  assert.throws(() => setTitleInputs(TEMPLATE_BA, { color: { r: 2 } }), /0\.\.1/);
+});