davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/vendor/drp-format/index.js

@@ -0,0 +1,174 @@
+/**
+ * DaVinci Resolve Project (DRP) Generator
+ *
+ * This module provides utilities for generating DaVinci Resolve Project files (.drp)
+ * with support for timelines, media pools, color grades, effects, markers, and project settings.
+ *
+ * Includes comprehensive encoding/decoding for:
+ * - Grade parameters (color wheels, adjustments)
+ * - Node trees (serial, parallel, layer mixers)
+ * - Custom curves (RGB, Hue vs Sat/Lum, etc.)
+ * - Qualifiers (HSL, luminance, 3D)
+ * - Power windows (circle, linear, polygon, curve)
+ *
+ * @module drp-generator
+ */
+
+const xmlBuilder = require('./xml-builder');
+const gradeEncoder = require('./grade-encoder');
+const drpPackager = require('./drp-packager');
+const effectEncoder = require('./effect-encoder');
+const markerEncoder = require('./marker-encoder');
+const injectGradesModule = require('./inject-grades');
+const diffModule = require('./diff');
+const extractLutRefsModule = require('./extract-lut-refs');
+
+/**
+ * High-level convenience: build a full DRP buffer from a spec.
+ *
+ * Spec shape:
+ *   {
+ *     projectName: string,
+ *     projectSettings: object,  // → buildProjectXml input
+ *     timelines: [{ name, frameRate, startTimecode, resolution,
+ *                   videoTracks, audioTracks, markers }],
+ *     mediaPool: object | null,
+ *     metadata: object,
+ *   }
+ *
+ * Returns a Buffer ready to write to disk as a .drp file.
+ */
+async function buildDRP(spec = {}) {
+  const projectSettings = {
+    projectName: spec.projectName || 'Untitled Project',
+    ...(spec.projectSettings || {}),
+  };
+  const projectXml = xmlBuilder.buildProjectXml(projectSettings);
+  return drpPackager.packageFullDRP({
+    projectXml,
+    timelines: spec.timelines || [],
+    mediaPool: spec.mediaPool || null,
+    metadata: {
+      projectName: projectSettings.projectName,
+      ...(spec.metadata || {}),
+    },
+  });
+}
+
+// Advanced grade encoding/decoding modules
+const gradeParameterDecoder = require('./grade-parameter-decoder');
+const nodeTreeEncoder = require('./node-tree-encoder');
+const curvesEncoder = require('./curves-encoder');
+const qualifierEncoder = require('./qualifier-encoder');
+const powerWindowEncoder = require('./power-window-encoder');
+
+module.exports = {
+  // XML Builder functions
+  ...xmlBuilder,
+
+  // Grade Encoder functions
+  ...gradeEncoder,
+
+  // DRP Packager functions
+  ...drpPackager,
+
+  // Effect Encoder functions
+  ...effectEncoder,
+
+  // Marker Encoder functions
+  ...markerEncoder,
+
+  // Grade Parameter Decoder functions
+  ...gradeParameterDecoder,
+
+  // Node Tree Encoder functions
+  ...nodeTreeEncoder,
+
+  // Curves Encoder functions
+  ...curvesEncoder,
+
+  // Qualifier Encoder functions
+  ...qualifierEncoder,
+
+  // Power Window Encoder functions
+  ...powerWindowEncoder,
+
+  // High-level convenience entry point
+  buildDRP,
+
+  // Grade injection into an existing DRP (P0.1)
+  injectGrades: injectGradesModule.injectGrades,
+
+  // Structural diff of two DRPs (P0.2)
+  diff: diffModule.diff,
+
+  // Diff module internals — exposed so the MCP extract_node_graphs
+  // action can walk the clip index without duplicating the SeqContainer
+  // walker. Not part of the supported public API; subject to change.
+  diffInternals: diffModule._internals,
+
+  // Project-level LUT reference extraction (P5.2 — clf-lut-bridge)
+  extractProjectLUTRefs: extractLutRefsModule.extractProjectLUTRefs,
+  LUT_RECOGNIZED_SLOTS: extractLutRefsModule.RECOGNIZED_SLOTS,
+
+  // Place a Fusion Title (Text+) on a chosen video track — the #74 track-targeting
+  // bypass (clone-based; carries a real CompositionBA verbatim).
+  placeFusionTitle: require('./place-fusion-title').placeFusionTitle,
+
+  // Place a built-in generator (Solid Color, etc.) on a chosen video track.
+  placeGenerator: require('./place-generator').placeGenerator,
+
+  // Insert a cross-dissolve between two abutting clips (the one op the Resolve API can't do).
+  placeTransition: require('./place-transition').placeTransition,
+
+  // Read/replace a Fusion Title's text + style (font/size/justify) inside a CompositionBA blob.
+  decodeTitleText: require('./composition-text').decodeTitleText,
+
+  // Fixed-size Media Pool/timeline metadata blobs (Resolution/FrameRate/MediaFrameRate/MediaExtents).
+  mediaBlobs: require('./media-blobs'),
+  // Reader for the Media Pool keyed-dict metadata blobs (Geometry/Time/VideoMetadata/Proxy).
+  keyedDict: require('./keyed-dict'),
+  // Per-clip retime/speed map (MediaTimemapBA) — [u8 type][BE float64 seconds].
+  mediaTimemap: require('./media-timemap'),
+  // Generic protobuf wire codec for Radiometry / EffectFiltersBA / protobuf FieldsBlob.
+  protobufWire: require('./protobuf-wire'),
+  setTitleText: require('./composition-text').setTitleText,
+  setTitleInputs: require('./composition-text').setTitleInputs,
+  decodeTitleInputs: require('./composition-text').decodeTitleInputs,
+
+  // In-place clip edits (move/delete/trim, optional track-scoped ripple) — generalizes #74.
+  moveClip: require('./splice-clips').moveClip,
+  deleteClip: require('./splice-clips').deleteClip,
+  trimClip: require('./splice-clips').trimClip,
+  trimClipHead: require('./splice-clips').trimClipHead,
+  splitClip: require('./splice-clips').splitClip,
+  rippleTimeline: require('./splice-clips').rippleTimeline,
+
+  // Create a fresh, importable Resolve project (one empty timeline) from a bundled template.
+  createEmptyProject: require('./author-project').createEmptyProject,
+
+  // Build a full importable timeline from a declarative spec (titles/generators/transitions).
+  assembleTimeline: require('./assemble-timeline').assembleTimeline,
+
+  // Author a project with one media clip referencing an arbitrary h264 file, from scratch [P8].
+  addMediaClip: require('./author-project').addMediaClip,
+
+  // Offline media relink — repoint media to new paths in the Media Pool blobs (no Resolve).
+  relinkMedia: require('./relink-media').relinkMedia,
+  // Relink + fix cached specs (resolution/frames/fps) for a differently-formatted file [P8].
+  repointMedia: require('./relink-media').repointMedia,
+
+  // Convenience re-exports for common operations
+  xml: xmlBuilder,
+  grade: gradeEncoder,
+  packager: drpPackager,
+  effect: effectEncoder,
+  marker: markerEncoder,
+
+  // Advanced encoding/decoding modules
+  gradeDecoder: gradeParameterDecoder,
+  nodeTree: nodeTreeEncoder,
+  curves: curvesEncoder,
+  qualifier: qualifierEncoder,
+  window: powerWindowEncoder,
+};

package/resolve-advanced/vendor/drp-format/inject-grades.js

@@ -0,0 +1,219 @@
+/**
+ * DaVinci Resolve DRP Grade Injection
+ *
+ * Replaces the per-clip <Body> grade payload inside SeqContainer XMLs of a
+ * DRP archive with new payloads carried by DRX files. The DRX file's own
+ * <Body>HEX</Body> blob and the clip's <Body>HEX</Body> blob use the same
+ * marker-byte+zstd-compressed-protobuf encoding, so the injection is byte
+ * substitution — no protobuf understanding required at this layer.
+ *
+ * Resolve emits SeqContainer*.xml under "SeqContainer/" in exported DRPs.
+ * The the packager writes them under "Primary1/". This module
+ * discovers the folder by scanning zip entries so both layouts work.
+ *
+ * @module drp-format/inject-grades
+ */
+
+const fs = require('node:fs/promises');
+const JSZip = require('jszip');
+
+/** Find all SeqContainer*.xml entries regardless of folder name. */
+function listSeqContainerEntries(zip) {
+  const out = [];
+  zip.forEach((relativePath, entry) => {
+    if (entry.dir) return;
+    // Match any "<anything>/SeqContainer<N>.xml" path.
+    if (/(^|\/)SeqContainer\d*\.xml$/.test(relativePath)) {
+      out.push(relativePath);
+    }
+  });
+  return out;
+}
+
+/**
+ * Extract the hex blob from a DRX XML string. The blob is the same payload
+ * (marker 0x81 + zstd-compressed protobuf) that lives inside a clip's
+ * <Body> field in a SeqContainer.
+ */
+function extractDrxBodyHex(drxContent) {
+  // Use a non-greedy match across the entire XML — fast-xml-parser would
+  // be overkill and would normalize whitespace we don't control.
+  const match = drxContent.match(/<Body>([\s\S]*?)<\/Body>/);
+  if (!match) {
+    throw new Error('DRX content has no <Body>HEX</Body> block');
+  }
+  // The hex stream may contain whitespace from how Resolve formats DRX
+  // exports — strip everything that isn't hex.
+  return match[1].replace(/[^0-9a-fA-F]/g, '');
+}
+
+/**
+ * Replace the <Body> content of the first clip in seqXml whose DbId
+ * matches targetDbId. Returns null when no match (caller must decide
+ * whether that's an error or just a miss across multiple SeqContainers).
+ *
+ * Scoping: the regex anchors on `<Sm2TiVideoClip ... DbId="<id>"` and
+ * runs forward to the matching `</Sm2TiVideoClip>`. Inside that range we
+ * replace exactly one <Body>HEX</Body>. If a clip has no Body yet (a
+ * brand-new clip with no grade) we don't synthesize the surrounding
+ * LmVersionTable scaffolding — that's a builder responsibility, not an
+ * injector one. Callers wanting to add grades to clean clips should
+ * build the DRP fresh via buildDRP with the grade in the spec.
+ */
+function replaceBodyForClip(seqXml, targetDbId, newBodyHex) {
+  // 1. Locate the clip element opening tag.
+  //    Sm2TiVideoClip is the post-monorepo tag (matches seq-container-builder).
+  //    Older / different layouts may use Sm2VideoClip — accept both.
+  const clipOpenRe = new RegExp(
+    `<(Sm2TiVideoClip|Sm2VideoClip)([^>]*?)DbId="${escapeRegex(targetDbId)}"([^>]*)>`,
+  );
+  const openMatch = seqXml.match(clipOpenRe);
+  if (!openMatch) return null;
+
+  const clipTag = openMatch[1];
+  const openStart = openMatch.index;
+  const openEnd = openStart + openMatch[0].length;
+
+  // 2. Find the matching close tag, respecting potential nesting (a clip
+  //    doesn't nest a clip of the same tag in practice — confirmed in the
+  //    builder — but we walk depth anyway to be defensive).
+  const closeTag = `</${clipTag}>`;
+  const openTag = `<${clipTag}`;
+  let depth = 1;
+  let cursor = openEnd;
+  while (depth > 0) {
+    const nextOpen = seqXml.indexOf(openTag, cursor);
+    const nextClose = seqXml.indexOf(closeTag, cursor);
+    if (nextClose === -1) return null;
+    if (nextOpen !== -1 && nextOpen < nextClose) {
+      depth += 1;
+      cursor = nextOpen + openTag.length;
+    } else {
+      depth -= 1;
+      cursor = nextClose + closeTag.length;
+    }
+  }
+  const clipEnd = cursor;
+
+  // 3. Within the clip's range, replace exactly one <Body>...</Body>.
+  const clipRange = seqXml.slice(openStart, clipEnd);
+  const bodyRe = /<Body>([\s\S]*?)<\/Body>/;
+  if (!bodyRe.test(clipRange)) return null;
+  const newClipRange = clipRange.replace(
+    bodyRe,
+    `<Body>${newBodyHex}</Body>`,
+  );
+
+  return seqXml.slice(0, openStart) + newClipRange + seqXml.slice(clipEnd);
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Inject DRX grade payloads into the matching clips of an existing DRP.
+ *
+ * @param {string} drpPath - Absolute path to the source .drp
+ * @param {Array<{clipId?: string, resolveId?: string, drxContent: string}>} grades
+ *   Each entry targets one clip by DbId (clipId is the canonical name;
+ *   resolveId is accepted as an alias for callers that use Resolve's
+ *   field naming). drxContent is the full DRX XML; we extract its <Body>
+ *   blob and inject it into the clip's <Body>.
+ * @param {object} [opts]
+ * @param {string} [opts.outputPath] - Where to write the modified DRP.
+ *   If omitted, the source file is overwritten in place atomically.
+ * @returns {Promise<{bytes: number, clipsInjected: number, misses: string[]}>}
+ *   bytes: size of the written DRP.
+ *   clipsInjected: number of grade entries that found their target.
+ *   misses: clip IDs that didn't match any SeqContainer's clip.
+ */
+async function injectGrades(drpPath, grades, opts = {}) {
+  if (typeof drpPath !== 'string') {
+    throw new TypeError('injectGrades: drpPath must be a string');
+  }
+  if (!Array.isArray(grades) || grades.length === 0) {
+    throw new TypeError('injectGrades: grades must be a non-empty array');
+  }
+
+  const sourceBuf = await fs.readFile(drpPath);
+  const zip = await JSZip.loadAsync(sourceBuf);
+
+  const seqPaths = listSeqContainerEntries(zip);
+  if (seqPaths.length === 0) {
+    throw new Error(`No SeqContainer*.xml found in ${drpPath}`);
+  }
+
+  // Cache each SeqContainer's XML in memory; rewrite only the ones whose
+  // content changes. Cheaper than per-clip re-read and keeps the original
+  // file order stable in the output zip.
+  const seqXmls = new Map();
+  for (const p of seqPaths) {
+    seqXmls.set(p, await zip.file(p).async('string'));
+  }
+
+  let clipsInjected = 0;
+  const misses = [];
+
+  for (const entry of grades) {
+    const targetId = entry.clipId || entry.resolveId;
+    if (!targetId) {
+      throw new Error('injectGrades: every grade entry needs clipId or resolveId');
+    }
+    if (typeof entry.drxContent !== 'string' || entry.drxContent.length === 0) {
+      throw new Error(`injectGrades: grade for clip ${targetId} has no drxContent`);
+    }
+
+    const bodyHex = extractDrxBodyHex(entry.drxContent);
+
+    let injected = false;
+    for (const p of seqPaths) {
+      const before = seqXmls.get(p);
+      const after = replaceBodyForClip(before, targetId, bodyHex);
+      if (after !== null) {
+        seqXmls.set(p, after);
+        injected = true;
+        break; // a clip appears in exactly one SeqContainer
+      }
+    }
+
+    if (injected) {
+      clipsInjected += 1;
+    } else {
+      misses.push(targetId);
+    }
+  }
+
+  // Write modified SeqContainer XMLs back into the zip in place.
+  for (const p of seqPaths) {
+    zip.file(p, seqXmls.get(p));
+  }
+
+  const outBuf = await zip.generateAsync({
+    type: 'nodebuffer',
+    compression: 'DEFLATE',
+    compressionOptions: { level: 6 },
+  });
+
+  const outputPath = opts.outputPath || drpPath;
+  if (opts.outputPath && opts.outputPath !== drpPath) {
+    await fs.writeFile(outputPath, outBuf);
+  } else {
+    // Atomic in-place overwrite.
+    const tmp = `${drpPath}.injecting`;
+    await fs.writeFile(tmp, outBuf);
+    await fs.rename(tmp, drpPath);
+  }
+
+  return { bytes: outBuf.length, clipsInjected, misses };
+}
+
+module.exports = {
+  injectGrades,
+  // Exposed for unit tests; not part of the public API.
+  _internals: {
+    listSeqContainerEntries,
+    extractDrxBodyHex,
+    replaceBodyForClip,
+  },
+};

package/resolve-advanced/vendor/drp-format/keyed-dict.js

@@ -0,0 +1,227 @@
+/**
+ * keyed-dict — read AND write the Media Pool metadata blob format shared by
+ * Geometry / Time / VideoMetadata / Proxy (the BtVideoInfo sub-blobs).
+ *
+ * Layout (all big-endian):
+ *   [u32 hdr=1][u32 count]
+ *   then `count` entries: [u32 keyLen][UTF-16BE key][value]
+ *   value = [u32 valType][u8 subType][payload]
+ *     valType 0x0a (STRING) : [u32 byteLen][UTF-16BE chars]
+ *     valType 0x0c (BYTES)  : [u32 byteLen][raw bytes]   (e.g. Resolution, FrameRate;
+ *                             also a NESTED keyed-dict — e.g. TracksBA → BtAudioTrack)
+ *     valType 0x02 (INT32)  : [i32 value]                (NumChannels, IdxTrack)
+ *     valType 0x03 (UINT32) : [u32 value]                (SampleRate, BitDepth)
+ *     valType 0x04/0x06 (I64): [i64 value, BigInt]       (Duration, StartTime)
+ *
+ * Audio config (BtAudioInfo) uses the SAME format: TracksBA = { "<idx>": BYTES(inner
+ * BtAudioTrack dict) }; the inner dict carries SampleRate/NumChannels/CodecName/
+ * ChannelLayout/BitDepth. VirtualAudioTrackBA = { ChannelsBA: BYTES(dict), AudioType }.
+ *
+ * The first key is always `UniqueId` (STRING UUID); the last is `DbType` (STRING)
+ * naming the concrete type (BtGeometry / BtVideoTime / BtVideoMetadata / BtVideoProxy).
+ *
+ * Verified by exact round-trip reconstruction against real Resolve 21 exports — encode()
+ * of decode() reproduces the original blob byte-for-byte. See knowledge/blob-map.md.
+ *
+ * @module drp-format/keyed-dict
+ */
+
+const T_BOOL = 0x01;    // 1-byte boolean (UI view-options: ShowSubtitle, …)
+const T_INT32 = 0x02;   // signed 32-bit
+const T_UINT32 = 0x03;  // unsigned 32-bit (sample rate, bit depth)
+const T_INT64A = 0x04;  // 64-bit int (duration, ProjectDbMigrationState)
+const T_INT64C = 0x05;  // 64-bit int (ProjectFeatures)
+const T_DOUBLE = 0x06;  // float64 (timemap XMax/LastValidYOffset; audio StartTime)
+const T_STRING = 0x0a;
+const T_BYTES = 0x0c;   // length-delimited; len 0xffffffff means null/empty
+const T_DATE = 0x10;    // fixed 9-byte timestamp (CreateTime/ModTime); raw hex, round-tripped
+
+function _utf16beDecode(buf) {
+  const sw = Buffer.alloc(buf.length);
+  for (let j = 0; j + 1 < buf.length; j += 2) { sw[j] = buf[j + 1]; sw[j + 1] = buf[j]; }
+  return sw.toString('utf16le');
+}
+function _utf16beEncode(str) {
+  const le = Buffer.from(str, 'utf16le');
+  const be = Buffer.alloc(le.length);
+  for (let j = 0; j + 1 < le.length; j += 2) { be[j] = le[j + 1]; be[j + 1] = le[j]; }
+  return be;
+}
+
+/**
+ * Parse a keyed-dict blob (hex string or Buffer) into typed entries.
+ * Returns { hdr, count, entries: [{ key, type, subType, value }] } where value is:
+ *   string  for T_STRING, hex string for T_BYTES, number for T_INT32.
+ * Throws if the bytes don't parse cleanly to the end (guards against wrong format).
+ */
+function decodeKeyedDict(input) {
+  const b = Buffer.isBuffer(input) ? input : Buffer.from(input, 'hex');
+  if (b.length < 8) throw new Error('keyed-dict too short');
+  const hdr = b.readUInt32BE(0);
+  const count = b.readUInt32BE(4);
+  let o = 8;
+  const entries = [];
+  while (o < b.length - 4) {
+    const kl = b.readUInt32BE(o);
+    if (!(kl >= 2 && kl <= 200 && kl % 2 === 0 && o + 4 + kl <= b.length)) break;
+    const key = _utf16beDecode(b.slice(o + 4, o + 4 + kl));
+    o += 4 + kl;
+    const valType = b.readUInt32BE(o); o += 4;
+    const subType = b[o]; o += 1;
+    let value;
+    if (valType === T_STRING) {
+      const ln = b.readUInt32BE(o); o += 4;
+      value = _utf16beDecode(b.slice(o, o + ln)); o += ln;
+    } else if (valType === T_BYTES) {
+      const ln = b.readUInt32BE(o); o += 4;
+      if (ln === 0xffffffff) { value = null; } // null/empty marker — no payload
+      else { value = b.slice(o, o + ln).toString('hex'); o += ln; }
+    } else if (valType === T_BOOL) {
+      value = b[o] !== 0; o += 1;
+    } else if (valType === T_INT32) {
+      value = b.readInt32BE(o); o += 4;
+    } else if (valType === T_UINT32) {
+      value = b.readUInt32BE(o); o += 4;
+    } else if (valType === T_INT64A || valType === T_INT64C) {
+      value = b.readBigInt64BE(o); o += 8;
+    } else if (valType === T_DOUBLE) {
+      value = b.readDoubleBE(o); o += 8;
+    } else if (valType === T_DATE) {
+      value = b.slice(o, o + 9).toString('hex'); o += 9;
+    } else {
+      throw new Error(`keyed-dict unknown valType 0x${valType.toString(16)} at ${o - 5} (key=${key})`);
+    }
+    entries.push({ key, type: valType, subType, value });
+  }
+  return { hdr, count, entries };
+}
+
+/** Re-encode a parsed keyed-dict ({ hdr, count, entries }) to a Buffer (round-trips exactly). */
+function encodeKeyedDict({ hdr = 1, entries }) {
+  const parts = [];
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(hdr, 0);
+  head.writeUInt32BE(entries.length, 4);
+  parts.push(head);
+  for (const e of entries) {
+    const keyBuf = _utf16beEncode(e.key);
+    const kh = Buffer.alloc(4); kh.writeUInt32BE(keyBuf.length, 0);
+    parts.push(kh, keyBuf);
+    const vh = Buffer.alloc(5);
+    vh.writeUInt32BE(e.type, 0); vh.writeUInt8(e.subType || 0, 4);
+    parts.push(vh);
+    if (e.type === T_STRING) {
+      const sb = _utf16beEncode(e.value);
+      const lh = Buffer.alloc(4); lh.writeUInt32BE(sb.length, 0);
+      parts.push(lh, sb);
+    } else if (e.type === T_BYTES) {
+      if (e.value === null) {
+        const lh = Buffer.alloc(4); lh.writeUInt32BE(0xffffffff, 0);
+        parts.push(lh);
+      } else {
+        const raw = Buffer.from(e.value, 'hex');
+        const lh = Buffer.alloc(4); lh.writeUInt32BE(raw.length, 0);
+        parts.push(lh, raw);
+      }
+    } else if (e.type === T_BOOL) {
+      parts.push(Buffer.from([e.value ? 1 : 0]));
+    } else if (e.type === T_INT32) {
+      const ib = Buffer.alloc(4); ib.writeInt32BE(e.value | 0, 0);
+      parts.push(ib);
+    } else if (e.type === T_UINT32) {
+      const ib = Buffer.alloc(4); ib.writeUInt32BE(e.value >>> 0, 0);
+      parts.push(ib);
+    } else if (e.type === T_INT64A || e.type === T_INT64C) {
+      const ib = Buffer.alloc(8); ib.writeBigInt64BE(BigInt(e.value), 0);
+      parts.push(ib);
+    } else if (e.type === T_DOUBLE) {
+      const db = Buffer.alloc(8); db.writeDoubleBE(e.value, 0);
+      parts.push(db);
+    } else if (e.type === T_DATE) {
+      parts.push(Buffer.from(e.value, 'hex'));
+    } else {
+      throw new Error(`keyed-dict cannot encode valType 0x${e.type.toString(16)}`);
+    }
+  }
+  return Buffer.concat(parts);
+}
+
+/** Tolerant reader: [{ key, value }] (value = decoded string/number/hex). Back-compat. */
+function readKeyedDict(input) {
+  return decodeKeyedDict(input).entries.map((e) => ({ key: e.key, value: e.value }));
+}
+
+/** The concrete DbType name (BtGeometry / BtVideoTime / …) declared in the blob. */
+function keyedDictType(input) {
+  const e = decodeKeyedDict(input).entries.find((x) => x.key === 'DbType');
+  return e ? e.value : null;
+}
+
+/** Get a single entry's value by key (typed). */
+function getKeyedValue(input, key) {
+  const e = decodeKeyedDict(input).entries.find((x) => x.key === key);
+  return e ? e.value : undefined;
+}
+
+/** Set a single entry's value by key, returning a re-encoded hex string. Preserves order/type. */
+function setKeyedValue(input, key, value) {
+  const parsed = decodeKeyedDict(input);
+  const e = parsed.entries.find((x) => x.key === key);
+  if (!e) throw new Error(`keyed-dict has no key ${key}`);
+  e.value = value;
+  return encodeKeyedDict(parsed).toString('hex');
+}
+
+/**
+ * Read audio config from a TracksBA blob: returns an array of per-track objects
+ * { idx, sampleRate, numChannels, codecName, channelLayout, bitDepth, … } by
+ * recursively decoding each track's nested BYTES dict.
+ */
+function readAudioTracks(input) {
+  const outer = decodeKeyedDict(input);
+  const tracks = [];
+  for (const e of outer.entries) {
+    if (e.type !== T_BYTES) continue; // skip non-track scalar entries
+    let inner;
+    try { inner = decodeKeyedDict(Buffer.from(e.value, 'hex')); } catch { continue; }
+    const m = Object.fromEntries(inner.entries.map((x) => [x.key, x.value]));
+    if (m.DbType !== 'BtAudioTrack') continue;
+    tracks.push({
+      idx: e.key,
+      sampleRate: m.SampleRate,
+      numChannels: m.NumChannels,
+      codecName: m.CodecName,
+      channelLayout: m.ChannelLayout,
+      bitDepth: m.BitDepth,
+      startTime: m.StartTime,
+      duration: m.Duration,
+    });
+  }
+  return tracks;
+}
+
+/**
+ * Classify any Resolve metadata blob by its leading bytes — useful for the
+ * heterogeneous FieldsBlob (which is a keyed-dict for small element state but a
+ * zstd-compressed protobuf for large internal/UI/cache state).
+ *   'keyed-dict'  : [u32 hdr=1][u32 count] …            (decode with decodeKeyedDict)
+ *   'protobuf'    : [u32 hdr=2][u32 len][protobuf]       (decode with decodeEffectFilters)
+ *   'zstd'        : protobuf envelope wrapping a zstd frame (magic 28 b5 2f fd) —
+ *                   internal state, carried verbatim (Node lacks built-in zstd)
+ *   'unknown'     : none of the above
+ */
+function classifyBlob(input) {
+  const b = Buffer.isBuffer(input) ? input : Buffer.from(input, 'hex');
+  if (b.length >= 8 && b.indexOf(Buffer.from('28b52ffd', 'hex')) >= 0) return 'zstd';
+  const hdr = b.length >= 4 ? b.readUInt32BE(0) : -1;
+  if (hdr === 1) return 'keyed-dict';
+  if (hdr === 2) return 'protobuf';
+  return 'unknown';
+}
+
+module.exports = {
+  decodeKeyedDict, encodeKeyedDict,
+  readKeyedDict, keyedDictType, getKeyedValue, setKeyedValue, readAudioTracks,
+  classifyBlob,
+  T_BOOL, T_INT32, T_UINT32, T_INT64A, T_INT64C, T_DOUBLE, T_STRING, T_BYTES, T_DATE,
+};