davinci-resolve-mcp 4.9.2 → 4.10.0

package/resolve-advanced/server/subtitle-db.mjs

@@ -0,0 +1,285 @@
+/** Transactional subtitle edits in a CLOSED local project library. */
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { z } from 'zod';
+import { openGuarded, requireResolveQuit, snapshotBackup } from './db-patch.mjs';
+const require = createRequire(import.meta.url);
+const { decodeCaption, encodeCaption, checkCaptions } = require('../vendor/drp-format/subtitle-captions.js');
+const { decodePreset, setPresetInputs } = require('../vendor/drp-format/subtitle-preset.js');
+
+const target = { projectDb: z.string().optional(), projectName: z.string().optional() };
+const track = { timeline: z.string(), track: z.number().int().min(1).default(1) };
+const write = { dryRun: z.boolean().default(false), iConfirmProjectClosed: z.boolean().optional() };
+const frame = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const word = z.object({ text: z.string().min(1), start: z.number().nonnegative(), end: z.number().nonnegative() }).strict();
+const caption = { text: z.string().min(1), start: frame, end: frame, words: z.array(word).min(1) };
+const rgb = z.number().min(0).max(1);
+const inputs = z.object({
+  font: z.string().min(1).optional(), fontStyle: z.string().min(1).optional(),
+  size: z.number().positive().max(1).optional(), position: z.tuple([rgb, rgb]).optional(),
+  textRed: rgb.optional(), textGreen: rgb.optional(), textBlue: rgb.optional(), textAlpha: rgb.optional(),
+  highlightRed: rgb.optional(), highlightGreen: rgb.optional(), highlightBlue: rgb.optional(),
+  outlineRed: rgb.optional(), outlineGreen: rgb.optional(), outlineBlue: rgb.optional(),
+  outlineEnabled: z.union([z.literal(0), z.literal(1)]).optional(), thickness: z.number().min(0).max(1).optional(),
+}).strict();
+export const subtitleSchemas = {
+  list_subtitle_presets: z.object({ ...target, timeline: z.string().optional() }).strict(),
+  list_captions: z.object({ ...target, ...track }).strict(),
+  check_captions: z.object({ ...target, ...track, maxCharacters: z.number().int().positive().default(24) }).strict(),
+  write_captions: z.object({ ...target, ...track, ...write,
+    add: z.array(z.object(caption).strict()).default([]),
+    replace: z.array(z.object({ id: z.string(), ...caption }).strict()).default([]),
+    delete: z.array(z.string()).default([]), templateCaptionId: z.string().optional(),
+  }).strict(),
+  copy_subtitle_preset: z.object({ ...target, ...track, ...write,
+    sourceProject: z.string().optional(), sourceProjectDb: z.string().optional(), sourceTimeline: z.string(),
+    sourceTrack: z.number().int().positive().default(1), replace: z.boolean().default(false), inputs: inputs.optional(),
+  }).strict(),
+  set_subtitle_preset: z.object({ ...target, ...track, ...write, inputs }).strict(),
+};
+
+const quote = (s) => `"${s.replace(/"/g, '""')}"`;
+function guard(db, table, columns) {
+  const names = db.prepare(`PRAGMA table_info(${quote(table)})`).all().map((r) => r.name);
+  for (const c of columns) if (!names.includes(c)) throw new Error(`unsupported schema: missing ${table}.${c}`);
+  return names;
+}
+function tracks(db, timeline) {
+  guard(db, 'Sm2TiTrack', ['Sm2TiTrack_id', 'Sequence', 'Type']);
+  guard(db, 'Sm2Sequence', ['Sm2Sequence_id', 'Sm2Timeline_id', 'FrameRate']);
+  guard(db, 'Sm2Timeline', ['Sm2Timeline_id', 'Name']);
+  const timelines = db.prepare('SELECT Sm2Timeline_id id, Name FROM Sm2Timeline').all();
+  if (timeline != null && timelines.filter((r) => r.Name === timeline).length !== 1) {
+    throw new Error(`timeline "${timeline}" missing or ambiguous`);
+  }
+  const rows = db.prepare(`SELECT tr.Sm2TiTrack_id id, tl.Name timeline, tl.Sm2Timeline_id timelineId,
+    sq.Sm2Sequence_id sequenceId, sq.FrameRate fpsBlob
+    FROM Sm2TiTrack tr JOIN Sm2Sequence sq ON tr.Sequence=sq.Sm2Sequence_id
+    JOIN Sm2Timeline tl ON tl.Sm2Timeline_id=sq.Sm2Timeline_id WHERE tr.Type=2 ORDER BY tl.rowid,tr.rowid`).all();
+  // Resolve's vector association defines visible track order, not insertion order.
+  const associations = ['Sm2Sequence_Sm2TiTrack', 'Sm2SequenceContainer_Sm2TiTrack']
+    .filter((name) => db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name));
+  const order = associations.flatMap((name) => {
+    guard(db, name, ['DbOwner', 'DbAssociate', 'DbPropertyName', 'DbIndex']);
+    return db.prepare(`SELECT * FROM ${name} WHERE DbPropertyName='SubtitleTrackVec'`).all();
+  });
+  if (order.length) {
+    for (const r of rows) {
+      const links = order.filter((a) => a.DbAssociate === r.id);
+      if (links.length !== 1) throw new Error('unsupported subtitle track vector association');
+      r.order = links[0].DbIndex;
+    }
+    rows.sort((a, b) => a.timelineId.localeCompare(b.timelineId) || a.order - b.order);
+  } else if (rows.some((r, i) => rows.some((other, j) => j !== i && r.timelineId === other.timelineId))) {
+    throw new Error('multiple subtitle tracks require SubtitleTrackVec ordering');
+  }
+  const counts = new Map();
+  return rows.map((r) => {
+    const n = (counts.get(r.timelineId) || 0) + 1; counts.set(r.timelineId, n);
+    return { ...r, track: n };
+  }).filter((r) => timeline == null || r.timeline === timeline);
+}
+function selectedTrack(db, p) {
+  const row = tracks(db, p.timeline).find((r) => r.track === p.track);
+  if (!row) throw new Error(`no subtitle track ${p.track} on timeline "${p.timeline}"`);
+  const b = row.fpsBlob;
+  if (!b || b.length !== 16) throw new Error('unsupported timeline FrameRate encoding');
+  const fps = Buffer.from(b).readDoubleLE(0);
+  if (!Number.isFinite(fps) || fps < 1 || fps > 240) throw new Error('invalid timeline frame rate');
+  return { ...row, fps };
+}
+function items(db, tr, property) {
+  guard(db, 'Sm2TiItem', ['Sm2TiItem_id', 'DbType', 'Name', 'Start', 'Duration', 'FieldsBlob', 'Sm2TiTrack_id', 'CompositionTable']);
+  guard(db, 'Sm2TiItem_Sm2TiTrack', ['DbOwner', 'DbAssociate', 'DbPropertyName', 'DbIndex']);
+  const links = db.prepare('SELECT * FROM Sm2TiItem_Sm2TiTrack WHERE DbOwner=? AND DbPropertyName=? ORDER BY DbIndex').all(tr.id, property);
+  return links.map((link) => {
+    const row = db.prepare('SELECT * FROM Sm2TiItem WHERE Sm2TiItem_id=?').get(link.DbAssociate);
+    if (!row || row.Sm2TiTrack_id !== tr.id) throw new Error('dangling or inconsistent subtitle item association');
+    return { row, link };
+  });
+}
+function captions(db, tr) {
+  return items(db, tr, 'Items').map(({ row, link }) => {
+    if (row.DbType !== 'Sm2TiGenerator' || row.PrettyType !== 'Subtitle') throw new Error('unsupported item on subtitle track');
+    const start = Number(row.Start), duration = Number(row.Duration);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(duration)) throw new Error('invalid caption frame columns');
+    return { row, link, decoded: { id: row.Sm2TiItem_id,
+      ...decodeCaption(row.FieldsBlob, { name: row.Name || '', start, end: start + duration, fps: tr.fps }) } };
+  });
+}
+function preset(db, tr) {
+  const holders = items(db, tr, 'FusionCompHolderItems');
+  if (holders.length > 1) throw new Error('multiple preset holders on one track; refusing ambiguous edit');
+  if (!holders.length) return null;
+  guard(db, 'Sm2TiCompositionTable', ['Sm2TiCompositionTable_id', 'Sm2TiItem_id', 'CompositionBA']);
+  const { row, link } = holders[0];
+  if (row.DbType !== 'Sm2TiVideoClip') throw new Error('unsupported preset holder type');
+  const comp = db.prepare('SELECT * FROM Sm2TiCompositionTable WHERE Sm2TiCompositionTable_id=?').get(row.CompositionTable);
+  if (!comp || comp.Sm2TiItem_id !== row.Sm2TiItem_id) throw new Error('dangling preset composition');
+  return { row, link, comp, decoded: decodePreset(comp.CompositionBA) };
+}
+function insert(db, table, row) {
+  const cols = guard(db, table, Object.keys(row));
+  if (cols.length !== Object.keys(row).length) throw new Error(`source/target ${table} schema mismatch`);
+  const keys = Object.keys(row);
+  db.prepare(`INSERT INTO ${quote(table)} (${keys.map(quote).join(',')}) VALUES (${keys.map(() => '?').join(',')})`)
+    .run(...keys.map((k) => row[k]));
+}
+function exclusive(db, row) {
+  const links = db.prepare('SELECT * FROM Sm2TiItem_Sm2TiTrack WHERE DbAssociate=?').all(row.Sm2TiItem_id);
+  if (links.length !== 1) throw new Error('shared subtitle item; refusing to mutate');
+  for (const key of ['MediaRef', 'pLmVerTable', 'pAuxLmVerTable', 'OriginalClip', 'Sm2TiItem_Owner_id', 'TextRenderItemVec', 'Thumbnail', 'Group', 'ClipGroup']) {
+    if (row[key]) throw new Error(`unsupported subtitle dependency ${key}; refusing to mutate`);
+  }
+}
+function removeItem(db, row) {
+  exclusive(db, row);
+  if (row.CompositionTable) {
+    const refs = db.prepare('SELECT Sm2TiItem_id FROM Sm2TiItem WHERE CompositionTable=?').all(row.CompositionTable);
+    const comp = db.prepare('SELECT * FROM Sm2TiCompositionTable WHERE Sm2TiCompositionTable_id=?').get(row.CompositionTable);
+    if (refs.length !== 1 || !comp || comp.Sm2MpMedia_id || comp.Sm2CompositionTableManager_id) throw new Error('shared/unsupported preset composition');
+    db.prepare('DELETE FROM Sm2TiCompositionTable WHERE Sm2TiCompositionTable_id=?').run(row.CompositionTable);
+  }
+  db.prepare('DELETE FROM Sm2TiItem_Sm2TiTrack WHERE DbAssociate=?').run(row.Sm2TiItem_id);
+  db.prepare('DELETE FROM Sm2TiItem WHERE Sm2TiItem_id=?').run(row.Sm2TiItem_id);
+}
+function captionEdit(db, p, mutate) {
+  const tr = selectedTrack(db, p), current = captions(db, tr);
+  const byId = new Map(current.map((c) => [c.decoded.id, c]));
+  const ids = [...p.delete, ...p.replace.map((c) => c.id)];
+  if (!p.add.length && !ids.length) throw new Error('no caption changes requested');
+  if (new Set(ids).size !== ids.length) throw new Error('duplicate/conflicting caption ids');
+  for (const id of ids) {
+    if (!byId.has(id)) throw new Error(`caption ${id} is not on the selected track`);
+    exclusive(db, byId.get(id).row);
+  }
+  const template = p.templateCaptionId ? byId.get(p.templateCaptionId) : current[0];
+  if (p.add.length && !template) throw new Error('adding captions requires an existing caption on this track as a schema template');
+  if (p.add.length) exclusive(db, template.row);
+  const staged = [];
+  for (const [fresh, list] of [[false, p.replace], [true, p.add]]) {
+    for (const c of list) {
+      if (c.text !== c.words.map((w) => w.text).join(' ') || c.words.some((w) => w.text !== w.text.trim())) {
+        throw new Error('caption text must equal the words joined with spaces; words must be trimmed');
+      }
+      const base = fresh ? template : byId.get(c.id);
+      if (base.row.CompositionTable) throw new Error('per-caption Fusion compositions are not supported');
+      const blob = encodeCaption(base.row.FieldsBlob, c, tr.fps, { fresh });
+      const id = fresh ? randomUUID() : c.id;
+      const decoded = { id, ...decodeCaption(blob, { name: c.text, start: c.start, end: c.end, fps: tr.fps }) };
+      const qc = checkCaptions([decoded], { fps: tr.fps });
+      // Tick quantisation can otherwise turn a positive input word into a blank.
+      // Half-tick boundary rounding is accepted; actual internal gaps are not.
+      const errors = qc.issues.filter((r) => r.severity !== 'warning');
+      if (errors.length) throw new Error(`invalid caption timing: ${JSON.stringify(errors)}`);
+      const row = { ...base.row, Sm2TiItem_id: id, Name: ` ${c.text}`, Start: String(c.start),
+        Duration: String(c.end - c.start), FieldsBlob: blob };
+      if (fresh) for (const key of ['MarkersBA', 'RenderCacheBA', 'ImportExportMetadataBA']) if (key in row) row[key] = null;
+      staged.push({ fresh, row, decoded });
+    }
+  }
+  const removed = new Set(ids);
+  const final = [...current.filter((c) => !removed.has(c.decoded.id)).map((c) => c.decoded), ...staged.map((c) => c.decoded)]
+    .sort((a, b) => a.start - b.start || a.id.localeCompare(b.id));
+  for (let i = 1; i < final.length; i++) if (final[i].start < final[i - 1].end) throw new Error('caption edits would leave overlapping captions');
+  if (mutate) {
+    for (const id of p.delete) removeItem(db, byId.get(id).row);
+    for (const c of staged) {
+      if (c.fresh) {
+        insert(db, 'Sm2TiItem', c.row);
+      } else db.prepare('UPDATE Sm2TiItem SET Name=?,Start=?,Duration=?,FieldsBlob=? WHERE Sm2TiItem_id=?')
+        .run(c.row.Name, c.row.Start, c.row.Duration, c.row.FieldsBlob, c.row.Sm2TiItem_id);
+    }
+    // Resolve enforces DbIndex>=0, and its (owner,property,index) primary key
+    // is ON CONFLICT REPLACE. Updating indices in place can silently DELETE a
+    // neighbour when captions swap order. Rebuild only this Items vector in the
+    // transaction, preserving each association's remaining columns.
+    db.prepare("DELETE FROM Sm2TiItem_Sm2TiTrack WHERE DbOwner=? AND DbPropertyName='Items'").run(tr.id);
+    final.forEach((c, i) => insert(db, 'Sm2TiItem_Sm2TiTrack', {
+      ...(byId.get(c.id)?.link || template.link), DbOwner: tr.id, DbAssociate: c.id, DbPropertyName: 'Items', DbIndex: i,
+    }));
+    const back = captions(db, tr);
+    if (JSON.stringify(back.map((c) => c.decoded)) !== JSON.stringify(final) || back.some((c, i) => c.link.DbIndex !== i)) {
+      throw new Error('caption readback mismatch; transaction rolled back');
+    }
+  }
+  return { timeline: p.timeline, track: p.track, fps: tr.fps, added: staged.filter((c) => c.fresh).map((c) => c.decoded.id),
+    replaced: p.replace.map((c) => c.id), deleted: p.delete, captions: final, check: checkCaptions(final, { fps: tr.fps }) };
+}
+function presetEdit(db, p, mutate, source) {
+  const tr = selectedTrack(db, p), before = preset(db, tr);
+  if (source && before && !p.replace) throw new Error('target already has a preset; use replace:true');
+  if (!source && !before) throw new Error('track has no animation preset; copy_subtitle_preset first');
+  const base = source || before;
+  if (before) exclusive(db, before.row);
+  if (!source && !Object.keys(p.inputs).length) throw new Error('no preset input changes requested');
+  const blob = p.inputs && Object.keys(p.inputs).length ? setPresetInputs(base.comp.CompositionBA, p.inputs) : Buffer.from(base.comp.CompositionBA);
+  const after = decodePreset(blob);
+  if (mutate) {
+    if (source) {
+      if (before) removeItem(db, before.row);
+      const itemId = randomUUID(), compId = randomUUID();
+      const row = { ...base.row, Sm2TiItem_id: itemId, Sm2TiTrack_id: tr.id, CompositionTable: compId };
+      if (row.Track) row.Track = tr.id;
+      const comp = { ...base.comp, Sm2TiCompositionTable_id: compId, Sm2TiItem_id: itemId, CompositionBA: blob };
+      insert(db, 'Sm2TiItem', row);
+      insert(db, 'Sm2TiCompositionTable', comp);
+      insert(db, 'Sm2TiItem_Sm2TiTrack', { ...base.link, DbOwner: tr.id, DbAssociate: itemId, DbIndex: 0 });
+    } else db.prepare('UPDATE Sm2TiCompositionTable SET CompositionBA=? WHERE Sm2TiCompositionTable_id=?')
+      .run(blob, before.comp.Sm2TiCompositionTable_id);
+    const back = preset(db, tr);
+    if (!Buffer.from(back.comp.CompositionBA).equals(blob) || JSON.stringify(back.decoded) !== JSON.stringify(after)) {
+      throw new Error('preset readback mismatch; transaction rolled back');
+    }
+  }
+  return { timeline: p.timeline, track: p.track, before: before?.decoded || null, after,
+    holderDuration: Number(base.row.Duration), note: 'Holder duration preserved from reference; render validation is required.' };
+}
+
+export async function subtitleDbAction(action, args, resolveDbPath) {
+  // Snake-case project selectors from the workflow brief are accepted aliases.
+  const aliases = { source_project: 'sourceProject', source_timeline: 'sourceTimeline',
+    target_project: 'projectName', target_timeline: 'timeline', project: 'projectName' };
+  args = { ...args };
+  for (const [a, b] of Object.entries(aliases)) if (a in args) {
+    if (b in args) throw new Error(`provide either ${a} or ${b}`);
+    args[b] = args[a]; delete args[a];
+  }
+  const p = subtitleSchemas[action].parse(args), dbPath = await resolveDbPath(p);
+  const db = openGuarded(dbPath);
+  let source;
+  try {
+    if (action === 'list_subtitle_presets') return { presets: tracks(db, p.timeline).map((tr) => {
+      const value = preset(db, tr);
+      return { timeline: tr.timeline, timelineId: tr.timelineId, track: tr.track, trackId: tr.id,
+        preset: value ? { id: value.row.Sm2TiItem_id, ...value.decoded, holderDuration: Number(value.row.Duration) } : null };
+    }) };
+    if (action === 'list_captions' || action === 'check_captions') {
+      const tr = selectedTrack(db, p), list = captions(db, tr).map((c) => c.decoded);
+      return { timeline: p.timeline, track: p.track, fps: tr.fps, timeUnit: 'timeline_frames',
+        ...(action === 'list_captions' ? { captions: list } : checkCaptions(list, { fps: tr.fps, maxCharacters: p.maxCharacters })) };
+    }
+    if (action === 'copy_subtitle_preset') {
+      const sourcePath = await resolveDbPath({ projectDb: p.sourceProjectDb, projectName: p.sourceProject });
+      const src = openGuarded(sourcePath);
+      try {
+        source = preset(src, selectedTrack(src, { timeline: p.sourceTimeline, track: p.sourceTrack }));
+        if (!source) throw new Error('source subtitle track has no animation preset');
+        exclusive(src, source.row);
+        if (source.comp.Sm2MpMedia_id || source.comp.Sm2CompositionTableManager_id) throw new Error('unsupported shared source composition');
+      } finally { src.close(); }
+    }
+    const preview = action === 'write_captions' ? captionEdit(db, p, false) : presetEdit(db, p, false, source);
+    if (p.dryRun) return { ...preview, dryRun: true, backup: null, verified: false };
+  } finally { db.close(); }
+  requireResolveQuit(p);
+  const backup = await snapshotBackup(dbPath);
+  requireResolveQuit(p); // Recheck after the asynchronous snapshot.
+  const writable = openGuarded(dbPath, { writable: true });
+  try {
+    const result = writable.transaction(() => action === 'write_captions'
+      ? captionEdit(writable, p, true) : presetEdit(writable, p, true, source))();
+    return { ...result, dryRun: false, backup, verified: true, validation: 'database_readback_only',
+      reopenRequired: true };
+  } finally { writable.close(); }
+}

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

@@ -472,11 +472,17 @@ export const drtTool = {
         // scan, subfolders are not). Inner format byte-verified against the
         // template harvest: protobuf{field2: keyedDict{"0": binId, ...},
         // field4: time-varint} in the [u32 2][u32 len][0x81][zstd] wrapper.
-        const { zstdRawFrame } = requireCjs('../../vendor/drp-format/timeline-markers-blob.js');
+        const { zstdRawFrame, lenDelim } = requireCjs('../../vendor/drp-format/timeline-markers-blob.js');
         const binIds = [...bins.values()].map((b) => b.id);
         const childDict = encodeKeyedDict({ hdr: 1, entries: binIds.map((id, i) => ({ key: String(i), type: 0x0a, subType: 0, value: id })) });
+        // field 2's length is a protobuf VARINT, not one raw byte: one bin's
+        // dict is 95 bytes and fits, two bins' is 182 and does not, so
+        // `[0x12, 182]` emitted a 0xb6 continuation byte that swallowed the
+        // dict's first byte and read as length 54 — the registry parsed back
+        // empty with neither bin in it. lenDelim() writes the same single byte
+        // for the one-bin case, so that blob is unchanged.
         const inner = Buffer.concat([
-          Buffer.from([0x12, childDict.length]), childDict,
+          lenDelim(2, childDict),
           Buffer.from([0x20]), Buffer.from('b6cba6a90d', 'hex'),
         ]);
         const frame = zstdRawFrame(inner);

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

@@ -3,7 +3,7 @@
  *
  * Closes documented scripting-API gaps by direct SQLite UPDATE. Every write is gated:
  * project must be CLOSED + auto-backup + schema guard + read-back verify (db-patch.mjs).
- * Needs optional `better-sqlite3`. See the design notes design notes.
+ * Uses better-sqlite3 or the node:sqlite fallback.
  *
  * list_folders — read media-pool folders (name + color + lock)
  * rename_folder — Sm2MpFolder.Name (API has NO RenameSubFolder)
@@ -18,6 +18,7 @@
  */
 
 import { z } from 'zod';
+import { subtitleDbAction, subtitleSchemas } from '../subtitle-db.mjs';
 import { createRequire } from 'node:module';
 import { resolveDbPath as _resolveDbPathRaw, responsiveRoots, openGuarded, backup, requireClosed } from '../db-patch.mjs';
 
@@ -104,8 +105,16 @@ function selectOne(db, table, col, value) {
 export const projectDbTool = {
   name: 'project_db',
   description:
-    'Beyond-the-API live Project.db patches (plain columns) — closes gaps the scripting API cannot. Project must be CLOSED (auto-backup + schema guard + verify). Actions: list_folders, rename_folder (no RenameSubFolder API), set_folder_color, list_clips, set_clip_marks, relayout_node_graphs (whole-project Cleanup Node Graph — rewrites node x/y in every graded version Body; grade content untouched; REQUIRES full Resolve quit+relaunch after patching, it caches open projects in memory), list_subtitle_styles, set_subtitle_style (caption font family/size/italic/weight + normalised position — the scripting API exposes NO subtitle styling; whole-track, not per-caption; same quit+relaunch requirement). Needs optional better-sqlite3.',
+    'Beyond-the-API Project.db patches: list_folders, rename_folder, set_folder_color, list_clips, set_clip_marks, relayout_node_graphs, list_subtitle_styles, set_subtitle_style (basic track font/position, NOT animation presets). ' +
+    'Subtitle actions: list_subtitle_presets(projectName|projectDb, timeline?) reads linked Fusion animation presets; ' +
+    'copy_subtitle_preset(sourceProject|sourceProjectDb, sourceTimeline, sourceTrack?, projectName|projectDb, timeline, track?, replace?, inputs?); ' +
+    'set_subtitle_preset(projectName|projectDb, timeline, track?, inputs) edits Word Highlight controls: font, fontStyle, size, position:[x,y], textRed/Green/Blue/Alpha, highlightRed/Green/Blue, outlineRed/Green/Blue, outlineEnabled:0|1, thickness; RGB 0..1. ' +
+    'list_captions(projectName|projectDb, timeline, track?) returns text, start/end and words plus originalWords; ' +
+    'write_captions(same selectors, add:[{text,start,end,words:[{text,start,end}]}]?, replace:[{id,text,start,end,words}]?, delete:[id]?, templateCaptionId?) edits/adds/deletes in one transaction; all times are absolute timeline frames, end exclusive, caption frames integers, word frames may be fractional; ' +
+    'check_captions(same selectors, maxCharacters?:24) flags timing gaps/zero lengths/overflow heuristics. Subtitle track defaults to 1. ' +
+    'New subtitle writes require Resolve fully QUIT (checked through the process list) and iConfirmProjectClosed:true; dryRun:true previews without writing. Unique SQLite snapshot backup, schema guards, atomic transaction and readback. Readback is not render verification. Uses better-sqlite3 or node:sqlite (Node 22.16+ / 23.8+); automatic Windows/macOS/Linux library discovery.',
   async handler({ action, args }) {
+    if (Object.hasOwn(subtitleSchemas, action)) return subtitleDbAction(action, args, resolveDbPath);
     if (action === 'list_folders') {
       const p = listFoldersSchema.parse(args);
       const db = openGuarded(await resolveDbPath(p), { table: 'Sm2MpFolder', column: 'Name' });

package/resolve-advanced/vendor/drp-format/subtitle-captions.js

@@ -0,0 +1,122 @@
+/** Resolve 21 caption FieldsBlob codec. Times exposed in timeline frames;
+ * f15/16 and f19/20 store 60 ticks/second; f21 is the original frame anchor.
+ * Unknown protobuf fields survive byte-for-byte. No source media is touched.
+ */
+const { unwrapEffectFilters, wrapEffectFilters } = require('./subtitle-style.js');
+
+function varint(value) {
+  let n = BigInt(value);
+  if (n < 0n) throw new Error('negative protobuf integer');
+  const bytes = [];
+  do { bytes.push(Number(n & 127n) | (n > 127n ? 128 : 0)); n >>= 7n; } while (n);
+  return Buffer.from(bytes);
+}
+function parse(buf) {
+  let p = 0;
+  const read = () => {
+    let n = 0n;
+    for (let i = 0; i < 10 && p < buf.length; i++) {
+      const b = buf[p++];
+      if (i === 9 && b > 1) throw new Error('protobuf integer overflow');
+      n |= BigInt(b & 127) << BigInt(i * 7);
+      if (!(b & 128)) return n;
+    }
+    throw new Error('truncated protobuf integer');
+  };
+  const out = [];
+  while (p < buf.length) {
+    const start = p, tag = Number(read()), field = Math.floor(tag / 8), wire = tag % 8;
+    if (!Number.isSafeInteger(tag) || !field || field > 536870911) throw new Error('invalid protobuf tag');
+    let value, bytes;
+    if (wire === 0) value = read();
+    else {
+      const size = wire === 2 ? Number(read()) : wire === 1 ? 8 : wire === 5 ? 4 : -1;
+      if (!Number.isSafeInteger(size) || size < 0 || size > buf.length - p) throw new Error('truncated/unsupported protobuf field');
+      bytes = buf.subarray(p, p + size); p += size;
+    }
+    out.push({ field, wire, value, bytes, raw: buf.subarray(start, p) });
+  }
+  return out;
+}
+function field(id, value) {
+  return typeof value === 'number'
+    ? Buffer.concat([varint(id * 8), varint(value)])
+    : Buffer.concat([varint(id * 8 + 2), varint(value.length), value]);
+}
+function safeNumber(n) {
+  const v = Number(n);
+  if (!Number.isSafeInteger(v) || v < 0) throw new Error('caption integer outside safe range');
+  return v;
+}
+function message(blob) {
+  const env = unwrapEffectFilters(Buffer.from(blob));
+  if (env.version !== 2) throw new Error('unsupported caption FieldsBlob version');
+  const outer = parse(env.protobuf), entries = outer.filter((r) => r.field === 1 && r.wire === 2);
+  if (entries.length !== 1) throw new Error('expected exactly one caption message');
+  return { outer, entry: entries[0], inner: parse(entries[0].bytes) };
+}
+function decodeCaption(blob, { name = '', start, end, fps }) {
+  if (!Number.isFinite(fps) || fps <= 0) throw new Error('positive timeline fps required');
+  if (!blob || !blob.length) return { text: name.trimStart(), start, end, words: [], originalWords: [], anchor: null };
+  const { inner } = message(blob);
+  const anchors = inner.filter((r) => r.field === 21 && r.wire === 0);
+  if (anchors.length > 1) throw new Error('multiple caption anchors');
+  const anchor = anchors.length ? safeNumber(anchors[0].value) : start;
+  const readWords = (textField, startField, endField) => {
+    const strings = inner.filter((r) => r.field === textField && r.wire === 2).map((r) => r.bytes.toString('utf8'));
+    const times = (id) => inner.filter((r) => r.field === id).flatMap((r) => {
+      if (r.wire === 0) return [safeNumber(r.value)];
+      throw new Error(`unsupported caption timing wire type for field ${id}`);
+    });
+    const starts = times(startField), ends = times(endField);
+    return { strings, starts, ends, words: strings.map((text, i) => ({ text: text.trimStart(),
+      start: starts[i] == null ? null : starts[i] * fps / 60 + start - anchor,
+      end: ends[i] == null ? null : ends[i] * fps / 60 + start - anchor })) };
+  };
+  const current = readWords(14, 15, 16), original = readWords(18, 19, 20);
+  const issues = [];
+  for (const [label, data] of [['current', current], ['original', original]]) {
+    if (data.strings.length !== data.starts.length || data.strings.length !== data.ends.length) issues.push(`${label}_word_count_mismatch`);
+  }
+  return { text: current.strings.length ? current.strings.join('').trimStart() : name.trimStart(),
+    start, end, words: current.words, originalWords: original.words, anchor, decodeIssues: issues };
+}
+function encodeCaption(blob, caption, fps, { fresh = false } = {}) {
+  const { outer, entry, inner } = message(blob);
+  const replaced = new Set([14, 15, 16, 21, ...(fresh ? [18, 19, 20] : [])]);
+  const parts = inner.filter((r) => !replaced.has(r.field)).map((r) => r.raw);
+  for (const w of caption.words) parts.push(field(14, Buffer.from(` ${w.text}`, 'utf8')));
+  for (const w of caption.words) parts.push(field(15, Math.round(w.start * 60 / fps)));
+  for (const w of caption.words) parts.push(field(16, Math.round(w.end * 60 / fps)));
+  parts.push(field(21, caption.start));
+  return wrapEffectFilters(Buffer.concat(outer.map((r) => r === entry ? field(1, Buffer.concat(parts)) : r.raw)));
+}
+
+function checkCaptions(captions, { maxCharacters = 24, fps = 30 } = {}) {
+  const issues = [], epsilon = 1e-6;
+  const sorted = [...captions].sort((a, b) => a.start - b.start);
+  for (let i = 0; i < sorted.length; i++) {
+    const c = sorted[i], add = (code, extra = {}) => issues.push({ id: c.id, code, ...extra });
+    const boundaryTolerance = fps / 120 + epsilon; // nearest 60 Hz tick
+    if (!(c.end > c.start)) add('invalid_caption_duration');
+    if (i && c.start < sorted[i - 1].end) add('caption_overlap', { previousId: sorted[i - 1].id });
+    const length = Math.max(...c.text.split(/\r?\n/).map((line) => [...line].length));
+    if (length > maxCharacters) add('overflow_length', { characters: length, maxCharacters, severity: 'warning' });
+    for (const code of c.decodeIssues || []) add(code);
+    if (!c.words.length) add('missing_word_timings');
+    let cursor = c.start;
+    c.words.forEach((w, word) => {
+      if (!Number.isFinite(w.start) || !Number.isFinite(w.end)) { add('missing_word_timing', { word }); return; }
+      if (w.end <= w.start) add('zero_or_negative_word_duration', { word });
+      const tolerance = word === 0 ? boundaryTolerance : epsilon;
+      if (w.start > cursor + tolerance) add('word_gap', { word, start: cursor, end: w.start });
+      if (w.start < cursor - tolerance) add('word_overlap', { word });
+      if (w.start < c.start - boundaryTolerance || w.end > c.end + boundaryTolerance) add('word_outside_caption', { word });
+      cursor = Math.max(cursor, w.end);
+    });
+    if (c.words.length && cursor < c.end - boundaryTolerance) add('word_gap', { start: cursor, end: c.end });
+  }
+  return { ok: issues.length === 0, issues, fps, maxCharacters,
+    note: 'Length is a heuristic, not a pixel-boundary or render check. Review burned-in frames.' };
+}
+module.exports = { decodeCaption, encodeCaption, checkCaptions, parse, field };

package/resolve-advanced/vendor/drp-format/subtitle-preset.js

@@ -0,0 +1,131 @@
+/** Word Highlight's nested Fusion composition. Patch literal inputs only;
+ * never execute Lua or discard the surrounding keyed envelope/tool graph. */
+const zlib = require('node:zlib');
+const TEMPLATE = 'Templates/Edit/Titles/Subtitles/Animated/Word Highlight';
+const INPUTS = {
+  font: 'Font', fontStyle: 'Style', size: 'Size', position: 'Center',
+  // The macro exposes Clone controls, but TextPlus renders shading element 1
+  // using these persisted inputs. Writing the clones alone leaves its fill
+  // at the template's default pale yellow (Green1=.92, Blue1=.52).
+  textRed: 'Red1', textGreen: 'Green1', textBlue: 'Blue1', textAlpha: 'Alpha1',
+  highlightRed: 'HighlightColorRed', highlightGreen: 'HighlightColorGreen', highlightBlue: 'HighlightColorBlue',
+  outlineRed: 'HOutlineR', outlineGreen: 'HOutlineG', outlineBlue: 'HOutlineB',
+  outlineEnabled: 'HOutline', thickness: 'HOutlineThickness',
+};
+function unpack(blob) {
+  const b = Buffer.from(blob);
+  const outer = zlib.inflateSync(b.subarray(4), { maxOutputLength: 32 * 1024 * 1024 });
+  if (b.readUInt32BE(0) !== outer.length) throw new Error('CompositionBA outer length mismatch');
+  const dataStart = outer.indexOf('Composition {');
+  if (dataStart < 4 || outer.readUInt32BE(dataStart - 4) !== outer.length - dataStart) {
+    throw new Error('unsupported CompositionBA keyed envelope (expected one composition)');
+  }
+  const marker = outer.indexOf('Compressed = true, }', dataStart);
+  if (marker < 0) throw new Error('unsupported uncompressed Fusion composition');
+  const lenOffset = outer.indexOf(0, marker) + 1;
+  if (lenOffset <= marker || lenOffset + 4 >= outer.length) throw new Error('invalid nested composition delimiter');
+  const inner = zlib.inflateSync(outer.subarray(lenOffset + 4), { maxOutputLength: 32 * 1024 * 1024, info: true });
+  if (inner.engine.bytesWritten !== outer.length - lenOffset - 4 || inner.buffer.length !== outer.readUInt32LE(lenOffset)) {
+    throw new Error('CompositionBA inner length/trailing bytes mismatch');
+  }
+  const header = outer.subarray(dataStart, lenOffset - 1).toString('utf8');
+  const ids = [...header.matchAll(/TEMPLATE_ID\s*=\s*"([^"\r\n]+)"/g)];
+  if (ids.length !== 1) throw new Error('composition must have one TEMPLATE_ID');
+  return { outer, dataStart, lenOffset, text: inner.buffer.toString('utf8'), templateId: ids[0][1] };
+}
+// Mask strings/comments while retaining offsets, so braces and input-like text
+// inside strings cannot change the target table.
+function mask(text) {
+  if (/\[(?:=*)\[/.test(text)) throw new Error('unsupported Lua long string in preset');
+  return text.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|--[^\r\n]*/g, (s) => ' '.repeat(s.length));
+}
+function table(text, pattern) {
+  const masked = mask(text), matches = [...masked.matchAll(pattern)];
+  if (matches.length !== 1) throw new Error('unsupported/ambiguous Word Highlight tool layout');
+  const open = masked.indexOf('{', matches[0].index);
+  let depth = 1, close = open + 1;
+  for (; close < masked.length && depth; close++) {
+    if (masked[close] === '{') depth++;
+    if (masked[close] === '}') depth--;
+  }
+  if (depth) throw new Error('unbalanced Fusion table');
+  return { start: open + 1, end: close - 1 };
+}
+function inputTable(text) {
+  const tool = table(text, /\bTemplate\s*=\s*TextPlus\s*\{/g);
+  const inputs = table(text.slice(tool.start, tool.end), /\bInputs\s*=\s*\{/g);
+  return { start: tool.start + inputs.start, end: tool.start + inputs.end };
+}
+function literal(value) {
+  if (typeof value === 'string') return JSON.stringify(value).replace(/\u2028/g, '\\n').replace(/\u2029/g, '\\n');
+  if (Array.isArray(value) && value.length === 2 && value.every(Number.isFinite)) return `{ ${value.join(', ')} }`;
+  if (Number.isFinite(value)) return String(value);
+  throw new Error('preset input must be a finite number, string, or position pair');
+}
+function parseLiteral(value) {
+  const s = value.trim();
+  if (/^"(?:[^"\\]|\\.)*"$/.test(s)) return JSON.parse(s);
+  if (/^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(s)) return Number(s);
+  const vector = /^\{\s*([^,]+),\s*([^,}]+),?\s*\}$/.exec(s);
+  if (vector && [Number(vector[1]), Number(vector[2])].every(Number.isFinite)) return [Number(vector[1]), Number(vector[2])];
+  throw new Error('input is not a supported literal');
+}
+function inputRange(text, name) {
+  const matches = [...mask(text).matchAll(new RegExp(`\\b${name}\\s*=\\s*Input\\s*\\{`, 'g'))];
+  if (!matches.length) return null;
+  if (matches.length !== 1) throw new Error(`ambiguous preset input ${name}`);
+  return { ...table(text, new RegExp(`\\b${name}\\s*=\\s*Input\\s*\\{`, 'g')), keyStart: matches[0].index };
+}
+function decodePreset(blob) {
+  const u = unpack(blob), values = {};
+  if (u.templateId === TEMPLATE) {
+    const range = inputTable(u.text), inputs = u.text.slice(range.start, range.end);
+    for (const [key, name] of Object.entries(INPUTS)) {
+      const r = inputRange(inputs, name);
+      if (!r) continue; // Missing inputs use Resolve's defaults; do not invent values.
+      const body = inputs.slice(r.start, r.end), value = /^\s*Value\s*=\s*([\s\S]*?),?\s*$/.exec(body);
+      if (value) { try { values[key] = parseLiteral(value[1].replace(/,\s*$/, '')); } catch { /* animated/expression */ } }
+    }
+  }
+  return { templateId: u.templateId, inputs: values, parameterEditingSupported: u.templateId === TEMPLATE };
+}
+function setPresetInputs(blob, changes) {
+  const u = unpack(blob);
+  if (u.templateId !== TEMPLATE) throw new Error('parameter edits currently support Word Highlight only; clone other presets unchanged');
+  for (const key of Object.keys(changes)) if (!INPUTS[key]) throw new Error(`unknown preset input ${key}`);
+  const current = decodePreset(blob).inputs;
+  if (Object.entries(changes).every(([k, v]) => JSON.stringify(current[k]) === JSON.stringify(v))) return Buffer.from(blob);
+  const range = inputTable(u.text);
+  let inputs = u.text.slice(range.start, range.end);
+  for (const [key, value] of Object.entries(changes)) {
+    const name = INPUTS[key];
+    if (!name) throw new Error(`unknown preset input ${key}`);
+    const r = inputRange(inputs, name), replacement = `${name} = Input { Value = ${literal(value)}, }, `;
+    if (r) {
+      const body = inputs.slice(r.start, r.end);
+      if (!/^\s*Value\s*=/.test(body) || /\b(?:Expression|SourceOp|Source)\s*=/.test(mask(body))) {
+        throw new Error(`refusing to replace connected/animated input ${name}`);
+      }
+      // Validate the entire body before replacing; preserve unusual inputs by refusing.
+      parseLiteral(body.replace(/^\s*Value\s*=\s*/, '').replace(/,\s*$/, ''));
+      const tail = inputs.slice(r.end + 1).replace(/^\s*,\s*/, '');
+      inputs = inputs.slice(0, r.keyStart) + replacement + tail;
+    } else {
+      // Resolve can omit the separator after its last input. Prepending a
+      // comma-terminated field preserves that valid Lua table unchanged.
+      inputs = ` ${replacement}${inputs}`;
+    }
+  }
+  const inner = Buffer.from(u.text.slice(0, range.start) + inputs + u.text.slice(range.end), 'utf8');
+  const len = Buffer.alloc(4); len.writeUInt32LE(inner.length);
+  const outer = Buffer.concat([u.outer.subarray(0, u.lenOffset), len, zlib.deflateSync(inner, { level: 9 })]);
+  outer.writeUInt32BE(outer.length - u.dataStart, u.dataStart - 4);
+  const outerLen = Buffer.alloc(4); outerLen.writeUInt32BE(outer.length);
+  const result = Buffer.concat([outerLen, zlib.deflateSync(outer)]);
+  const back = decodePreset(result);
+  for (const [key, value] of Object.entries(changes)) {
+    if (JSON.stringify(back.inputs[key]) !== JSON.stringify(value)) throw new Error(`preset readback mismatch: ${key}`);
+  }
+  return result;
+}
+module.exports = { decodePreset, setPresetInputs, TEMPLATE, INPUTS };

package/resolve-advanced/vendor/drp-format/subtitle-style.js

@@ -154,7 +154,11 @@ function unwrapEffectFilters(raw) {
     if (!payload.slice(0, 4).equals(ZSTD_MAGIC)) {
       throw new Error('EffectFiltersBA 0x81 payload is not a zstd frame');
     }
-    if (!fzstd) throw new Error("EffectFiltersBA 0x81 payload is zstd; optional dep 'fzstd' is required to decode");
+    const zlib = require('node:zlib');
+    if (typeof zlib.zstdDecompressSync === 'function') {
+      return { version, marker, protobuf: zlib.zstdDecompressSync(payload) };
+    }
+    if (!fzstd) throw new Error("zstd decoding needs fzstd or Node with zlib.zstdDecompressSync");
     return { version, marker, protobuf: Buffer.from(fzstd.decompress(new Uint8Array(payload))) };
   }
   throw new Error(`unknown EffectFiltersBA payload marker 0x${marker.toString(16)}`);

package/resolve-advanced/vendor/drp-format/timeline-markers-blob.js

@@ -156,4 +156,4 @@ function decodeTimelineMarkersBlob(buf) {
   return markers;
 }
 
-module.exports = { encodeTimelineMarkersBlob, decodeTimelineMarkersBlob, MARKER_COLOR_BITS, zstdRawFrame };
+module.exports = { encodeTimelineMarkersBlob, decodeTimelineMarkersBlob, MARKER_COLOR_BITS, zstdRawFrame, lenDelim };

package/src/granular/common.py

@@ -91,7 +91,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.9.2"
+VERSION = "4.10.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/granular/timeline_item.py

@@ -1390,6 +1390,9 @@ def ti_set_property(property_name: str, property_value: Any, item_index: int = 0
         track_type: 'video' or 'audio'. Default: 'video'.
         track_index: 1-based track index. Default: 1.
     """
+    if track_type == "subtitle":
+        return {"success": False, "error": "SetProperty is unsupported on subtitle items. "
+                "Use advanced project_db write_captions / set_subtitle_preset with Resolve fully quit."}
     item, err = _get_timeline_item(track_type, track_index, item_index)
     if err:
         return err