davinci-resolve-mcp 4.17.1 → 4.18.1

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v4.18.1 — Names with `$` or `\` are written as typed
+
+### Fixed
+
+- **`drt assemble_project` no longer rewrites a merged timeline's name when it
+  contains `$`** (#332, thanks @Dev-next-gen). The name was inserted with a
+  replacement string, and JavaScript expands `$&`, `$'` and `$$` in one. A
+  second timeline named `R2 $& $'` wrote an `MpFolder.xml` that no longer
+  parsed, and `Spot $$ 30s` came out as `Spot $ 30s`, so a `folder` move then
+  failed to find the timeline.
+- **The same fix in 53 more places in the offline `.drp`/`.drt` writers.**
+  Caption text in `placeSubtitles`, generator, title and compound clip names,
+  media pool clip names and file paths, and every other value inserted into
+  the XML now goes in with a replacer function, so `$`-sequences stay literal.
+  A new guard test fails the advanced suite if a `replace()` call passes an
+  interpolated template as a string.
+- **The audio-only fallback clone in `cut-media` now XML-escapes the source
+  file name and path.** A source path containing `&`, such as
+  `Smith & Jones/clip.mov`, wrote invalid XML.
+- **Re-running media analysis on a clip no longer fails when the new analysis
+  text contains a backslash.** The managed block in the clip's metadata was
+  replaced with `re.sub` using the text as a replacement string, so a Windows
+  path raised `bad escape \F` and `\t` turned into a tab. The text is now
+  inserted as-is.
+
+### Validation
+
+- Advanced Node suite on Node 20 with a fresh `npm ci`: 1,224 tests, 0 failed.
+  With the fixes reverted, the guard and the caption, generator and title tests
+  fail.
+- Python suite: the new metadata test fails with `bad escape \F` without the
+  fix and passes with it.
+- Offline file writers only. No Resolve API behaviour changed.
+
+## What's New in v4.18.0 — Edit captions with Resolve open
+
+### Added
+
+- **`timeline_ai.list_captions_live` and `timeline_ai.write_captions_live`**
+  (#330, thanks @sidevconcept). Caption text and per-word timing can now be
+  edited without quitting Resolve or patching the open Project.db.
+  `write_captions_live` takes the same `replace` / `add` / `delete` shape as
+  the offline `project_db` `write_captions`. It exports the timeline as a
+  native DRT, applies the edit with the same caption codec and edit checks,
+  and imports the result as a new timeline revision. The revision is selected
+  only after Resolve's own re-export of it keeps the requested text, caption
+  bounds and word frames. If any step fails, the original timeline stays
+  selected and unchanged.
+- A caption `id` is its start frame as a string, because Resolve issues new
+  item IDs on every export. The write returns the IDs to use for the next
+  edit, including for captions it added or moved. Edits on a track where two
+  captions share a start frame are refused as ambiguous.
+- `write_captions_live` is registered as a destructive action with a native
+  dry run (medium risk, recoverable). `list_captions_live` is read-only.
+
+### Changed
+
+- `set_subtitle_preset` now shares its export → edit → import → re-export
+  steps with the caption writer. Its behaviour and result fields are the same.
+
+### Limits
+
+- Word times keep the existing codec's 60 Hz tick quantisation.
+- Adding to an empty subtitle track needs an existing caption as a template.
+  Per-caption Fusion compositions are refused.
+- The structural readback does not check every grade, marker, Fusion
+  composition or audio property carried through the native timeline import.
+
+### Validation
+
+- Python suite with the PR merged on `main`: 4,294 tests. The only failures
+  are the 4 `source_media_guard` path checks that always fail in a scratch
+  worktree.
+- Advanced Node suite on Node 20 with a fresh `npm ci`: 1,218 tests, 1,157
+  passed, 0 failed, 61 skipped.
+- Live-validated by the contributor on Studio 21.1.0.17 with a disposable
+  project copy: three captions rewritten (one containing `$`), a moved
+  caption's ID reused, an added caption deleted by its returned ID, and a
+  burned-in render checked across nine word phases. Not live-validated on the
+  maintainer's Studio 19.1.3.7.
+
 ## What's New in v4.17.1 — Media analysis decodes each file once
 
 ### Changed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.17.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.18.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(390%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-4.17.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.18.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(390%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v4.17.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.18.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/SKILL.md

@@ -459,6 +459,15 @@ Operating rules an agent must know:
   Ordinary title presets use `timeline.insert_fusion_title` with the full ID,
   then scoped `fusion_comp` probes and input writes. See
   [title library automation](guides/title-library-automation.md) for acceptance.
+- **Live caption text and word timing**: `timeline_ai.list_captions_live` reads
+  one subtitle track's captions from a native DRT export, with Resolve open.
+  `timeline_ai.write_captions_live` takes the same `replace` / `add` / `delete`
+  shape as `project_db` `write_captions` and imports the result as a selected
+  revision. A caption `id` is its start frame as a string, because Resolve
+  issues new item IDs on every export; use the IDs the write returns for the
+  next edit. Resolve's re-export must keep the text, bounds and word frames,
+  or the original stays selected. Adding to an empty track needs an existing
+  caption as a template; per-caption Fusion compositions are refused.
 - **Offline subtitle DB edits**: `project_db` `list_captions` / `write_captions` /
   `check_captions` cover text, bounds, explicit per-word timing, add and delete.
   `list_subtitle_presets` / `copy_subtitle_preset` / `set_subtitle_preset` handle
@@ -1964,7 +1973,8 @@ against it, and image content fails that validation.
 
 Key actions: `create_subtitles(settings?)` (human-readable settings resolved to
 `SUBTITLE_*`/`AUTO_CAPTION_*` enums + read-back verified — see
-`subtitle_generation_probe`), `detect_scene_cuts`,
+`subtitle_generation_probe`), `list_captions_live`, `write_captions_live`,
+`detect_scene_cuts`,
 `grab_still`, `grab_all_stills(source?)`, `analyze_dolby_vision`
 
 ---

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.17.1"
+VERSION = "4.18.1"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "4.17.1",
+  "version": "4.18.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

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

@@ -155,19 +155,20 @@ function removeItem(db, row) {
   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);
+/** Validate and stage caption edits on decoded captions ({decoded, blob}); shared by Project.db and DRT writers. */
+export function planCaptionEdit(current, p, fps, checkBase = () => {}) {
   const byId = new Map(current.map((c) => [c.decoded.id, c]));
+  if (byId.size !== current.length) throw new Error('duplicate caption ids on selected track; refusing ambiguous edit');
   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);
+    checkBase(byId.get(id));
   }
   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);
+  if (p.add.length) checkBase(template);
   const staged = [];
   for (const [fresh, list] of [[false, p.replace], [true, p.add]]) {
     for (const c of list) {
@@ -175,25 +176,35 @@ function captionEdit(db, p, mutate) {
         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 blob = encodeCaption(base.blob, c, 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 });
+      const decoded = { id, ...decodeCaption(blob, { name: c.text, start: c.start, end: c.end, fps }) };
+      const qc = checkCaptions([decoded], { 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 });
+      staged.push({ fresh, base, caption: c, blob, 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');
+  return { byId, template, staged, final };
+}
+function captionEdit(db, p, mutate) {
+  const tr = selectedTrack(db, p);
+  const plan = planCaptionEdit(captions(db, tr).map((c) => ({ ...c, blob: c.row.FieldsBlob })), p, tr.fps,
+    (c) => exclusive(db, c.row));
+  const { byId, template, final } = plan;
+  const staged = plan.staged.map(({ fresh, base, caption: c, blob, decoded }) => {
+    if (base.row.CompositionTable) throw new Error('per-caption Fusion compositions are not supported');
+    const row = { ...base.row, Sm2TiItem_id: decoded.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;
+    return { fresh, row, decoded };
+  });
   if (mutate) {
     for (const id of p.delete) removeItem(db, byId.get(id).row);
     for (const c of staged) {

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

@@ -3,9 +3,10 @@ import fs from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 import JSZip from 'jszip';
-import { subtitleSchemas } from './subtitle-db.mjs';
+import { subtitleSchemas, planCaptionEdit } from './subtitle-db.mjs';
 const require = createRequire(import.meta.url);
 const { decodePreset, setPresetInputs } = require('../vendor/drp-format/subtitle-preset.js');
+const { decodeCaption } = require('../vendor/drp-format/subtitle-captions.js');
 const REFERENCES = { 'Word Highlight': 'word-highlight-track.xml', Lollipop: 'lollipop-track.xml' };
 
 async function readTimeline(path) {
@@ -81,3 +82,78 @@ export async function editSubtitleTimeline({ source, output, track = 1, inputs =
     editableInputs: decoded.editableInputs,
     verification: 'exported_preset_readback', restart_required: false };
 }
+
+// Caption items: same FieldsBlob codec as Project.db write_captions, but on the exported DRT.
+const xmlEscape = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const xmlUnescape = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+const tag = (xml, name) => {
+  const m = new RegExp(`<${name}>([^<]*)</${name}>|<${name}/>`).exec(xml);
+  if (!m) throw new Error(`caption item missing ${name}`);
+  return m[1] ?? '';
+};
+const setTag = (xml, name, value) => xml.replace(new RegExp(`<${name}>[^<]*</${name}>|<${name}/>`), () => `<${name}>${value}</${name}>`);
+async function sequenceFps(zip, track) {
+  const sequence = /<Sequence>([0-9a-f-]{36})<\/Sequence>/i.exec(track)?.[1];
+  if (!sequence) throw new Error('subtitle track has no sequence reference');
+  for (const name of Object.keys(zip.files).filter((n) => n.endsWith('.xml'))) {
+    const xml = await zip.file(name).async('string'), at = xml.indexOf(`<Sm2Sequence DbId="${sequence}">`);
+    if (at < 0) continue;
+    const hex = /<FrameRate>([0-9a-fA-F]{32})<\/FrameRate>/.exec(xml.slice(at, xml.indexOf('</Sm2Sequence>', at)))?.[1];
+    const fps = hex ? Buffer.from(hex, 'hex').readDoubleLE(0) : NaN;
+    if (!Number.isFinite(fps) || fps < 1 || fps > 240) throw new Error('unsupported timeline FrameRate encoding');
+    return fps;
+  }
+  throw new Error('timeline sequence not found in export');
+}
+function captionItems(track, fps) {
+  const m = /<Items>([\s\S]*?)<\/Items>|<Items\/>/.exec(track);
+  if (!m) throw new Error('Unsupported track: missing Items field');
+  const inner = m[1] ?? '';
+  const elements = [...inner.matchAll(/<Element>\s*<Sm2TiGenerator DbId="([0-9a-f-]{36})">[\s\S]*?<\/Sm2TiGenerator>\s*<\/Element>/gi)];
+  // Anything besides plain subtitle generators would be dropped by the rebuild below.
+  if (elements.reduce((rest, e) => rest.replace(e[0], ''), inner).trim()) throw new Error('unsupported item on subtitle track');
+  // Resolve issues fresh DbIds on every export, so a caption's id is its start frame
+  // (captions on a track never overlap); DbIds are only carried in the XML.
+  const items = elements.map(([text, dbId]) => {
+    if (tag(text, 'PrettyType') !== 'Subtitle') throw new Error('unsupported item on subtitle track');
+    if (/<CompositionTable>/.test(text)) throw new Error('per-caption Fusion compositions are not supported');
+    const start = Number(tag(text, 'Start')), duration = Number(tag(text, 'Duration'));
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(duration)) throw new Error('invalid caption frame columns');
+    const blob = Buffer.from(tag(text, 'FieldsBlob'), 'hex');
+    return { text, dbId, blob, decoded: { id: String(start), ...decodeCaption(blob, { name: xmlUnescape(tag(text, 'Name')), start, end: start + duration, fps }) } };
+  });
+  return { items, field: m, separator: /^\s*/.exec(inner)[0] || '\n' };
+}
+async function readCaptions(source, track) {
+  const exported = await readTimeline(source), target = selectedTrack(exported.xml, track);
+  const fps = await sequenceFps(exported.zip, target.text);
+  return { exported, target, fps, ...captionItems(target.text, fps) };
+}
+export async function inspectCaptionTimeline({ source, track = 1 }) {
+  const { fps, items } = await readCaptions(source, track);
+  return { track, fps, timeUnit: 'timeline_frames', captions: items.map((c) => c.decoded) };
+}
+export async function editCaptionTimeline({ source, output, track = 1, add = [], replace = [], delete: remove = [], templateCaptionId }) {
+  const p = subtitleSchemas.write_captions.parse({ timeline: 'export', track, add, replace, delete: remove, templateCaptionId });
+  if (source === output) throw new Error('Output must be a new file');
+  const { exported, target, fps, items, field, separator } = await readCaptions(source, track);
+  const { byId, template, staged, final } = planCaptionEdit(items, p, fps);
+  const stagedById = new Map(staged.map((s) => [s.decoded.id, s]));
+  const elements = final.map((c) => {
+    const s = stagedById.get(c.id);
+    if (!s) return byId.get(c.id).text;
+    let text = s.fresh ? template.text.replace(template.dbId, randomUUID()) : s.base.text;
+    if (s.fresh) text = text.replace(/<(MarkersBA|RenderCacheBA|ImportExportMetadataBA)>[\s\S]*?<\/\1>/g, '<$1/>');
+    text = setTag(text, 'FieldsBlob', s.blob.toString('hex'));
+    text = setTag(text, 'Name', xmlEscape(` ${s.caption.text}`));
+    text = setTag(text, 'Start', String(s.caption.start));
+    return setTag(text, 'Duration', String(s.caption.end - s.caption.start));
+  });
+  const trackText = target.text.slice(0, field.index) + `<Items>${separator}${elements.join(separator)}${separator}</Items>`
+    + target.text.slice(field.index + field[0].length);
+  exported.zip.file(exported.entry, exported.xml.slice(0, target.offset) + trackText + exported.xml.slice(target.offset + target.text.length));
+  await fs.writeFile(output, await exported.zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' }), { flag: 'wx' });
+  return { output, track, fps, added: staged.filter((s) => s.fresh).map((s) => String(s.caption.start)), replaced: p.replace.map((c) => c.id),
+    deleted: p.delete, captions: final.map((c) => ({ ...c, id: String(c.start) })),
+    verification: 'exported_caption_readback', restart_required: false };
+}

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

@@ -467,7 +467,7 @@ export const drtTool = {
           } catch { return whole; }
         });
         // pool clip: uuid remap + keyed SeqRef patch + fresh numeric IDs
-        let tlNew = applyBlobs(apply(tlEl)).replace(/<ID>\d+<\/ID>/g, `<ID>${nextPoolId}<\/ID>`.replace('<\/ID>', '</ID>'));
+        let tlNew = applyBlobs(apply(tlEl)).replace(/<ID>\d+<\/ID>/g, () => `<ID>${nextPoolId}<\/ID>`.replace('<\/ID>', '</ID>'));
         nextPoolId += 1;
         const fbM = tlNew.match(/(<Sm2Sequence DbId="[^"]+">\s*<FieldsBlob>)([0-9a-fA-F]+)(<\/FieldsBlob>)/);
         if (fbM) {
@@ -486,14 +486,14 @@ export const drtTool = {
         // Children live INSIDE <MediaVec> — an element appended after its
         // close parses fine and is silently invisible (measured: the whole
         // REEL_02 subtree vanished while every id chain checked out).
-        mpXml = mpXml.replace('</MediaVec>', `${tlNew}\n</MediaVec>`);
+        mpXml = mpXml.replace('</MediaVec>', () => `${tlNew}\n</MediaVec>`);
         for (const el of mediaEls) {
           const id = el.match(/DbId="([^"]+)"/)[1];
-          if (!mpXml.includes(`DbId="${id}"`)) mpXml = mpXml.replace('</MediaVec>', `${el}\n</MediaVec>`);
+          if (!mpXml.includes(`DbId="${id}"`)) mpXml = mpXml.replace('</MediaVec>', () => `${el}\n</MediaVec>`);
         }
         const pj2 = await zip.file('project.xml').async('string');
         for (const blob of pj2.match(/<Element>\s*<Sm2(?:Sequence|TiItem)LockableBlob DbId="[^"]+">[\s\S]*?<\/Sm2(?:Sequence|TiItem)LockableBlob>\s*<\/Element>/g) || []) {
-          pjXml = pjXml.replace('</LocableBlobSet>', `${apply(blob)}</LocableBlobSet>`);
+          pjXml = pjXml.replace('</LocableBlobSet>', () => `${apply(blob)}</LocableBlobSet>`);
         }
         // THE timeline registry (found the hard way — two invisible merges):
         // project.xml's <TimelineHandleVec> lists each pool clip's embedded
@@ -503,7 +503,7 @@ export const drtTool = {
         const vec2 = pj2.match(/<TimelineHandleVec>([\s\S]*?)<\/TimelineHandleVec>/);
         if (vec2) {
           for (const h of vec2[1].match(/<Element>[^<]*<\/Element>/g) || []) {
-            pjXml = pjXml.replace('</TimelineHandleVec>', ` ${apply(h)}\n </TimelineHandleVec>`);
+            pjXml = pjXml.replace('</TimelineHandleVec>', () => ` ${apply(h)}\n </TimelineHandleVec>`);
           }
         }
         // future merges must not collide with THIS timeline's fresh ids either
@@ -534,7 +534,7 @@ export const drtTool = {
           const hit = mpXml.match(tlRe);
           if (!hit) throw new Error(`assemble_project: could not locate pool clip for timeline ${names[i]} to move into folder ${folder}`);
           mpXml = mpXml.replace(hit[0], '');
-          bin.clips.push(hit[0].replace(/<MpFolder>[^<]*<\/MpFolder>/, `<MpFolder>${bin.id}</MpFolder>`));
+          bin.clips.push(hit[0].replace(/<MpFolder>[^<]*<\/MpFolder>/, () => `<MpFolder>${bin.id}</MpFolder>`));
         }
         // Register the bins in Master's FieldsBlob — the parent folder blob
         // is the SUBFOLDER registry (measured: with it blanked, a bin's

package/resolve-advanced/vendor/audio/format-converter.js

@@ -213,7 +213,7 @@ async function convert(inputPath, outputPath, options = {}) {
   // Auto-generate output path if not provided
   if (!outputPath) {
     const ext = CONTAINER_EXTENSIONS[preset.container] || '.wav';
-    outputPath = inputPath.replace(/\.[^.]+$/, `_${presetName}${ext}`);
+    outputPath = inputPath.replace(/\.[^.]+$/, () => `_${presetName}${ext}`);
   }
 
   onProgress(10);

package/resolve-advanced/vendor/drp-format/__tests__/literal-replacement.test.js

@@ -0,0 +1,95 @@
+// A string passed as the replacement to String.prototype.replace expands `$&`,
+// `$'`, `` $` `` and `$$`, so a name or caption carrying them is rewritten on its
+// way into the XML (#332: `R2 $& $'` as a timeline name made MpFolder.xml
+// unparseable; `Spot $$ 30s` came out as `Spot $ 30s`). Interpolated
+// replacements are therefore passed as functions, which insert their result
+// literally. This file guards that rule and checks the writers that carry user
+// text.
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const JSZip = require('jszip');
+const { escapeXml } = require('../xml-builder');
+const { createEmptyProject } = require('../author-project');
+const { placeSubtitles } = require('../place-subtitles');
+const { placeGenerator } = require('../place-generator');
+const { placeFusionTitle } = require('../place-fusion-title');
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const TRICKY = "Spot $$ 30s $& $' $` end";
+
+function sourceFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...sourceFiles(full));
+    else if (/\.(m?js)$/.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+// `.replace(<string or regex literal>, `...${...}...`)` on one line. A template
+// that uses a $-backreference ($1, $&, $<name>) needs the string form and is allowed.
+const STRING_REPLACEMENT = /\.replace\(\s*(?:'(?:[^'\\\n]|\\.)*'|"(?:[^"\\\n]|\\.)*"|\/(?:[^/\\\n]|\\.)+\/[a-z]*)\s*,\s*`((?:[^`\\]|\\.)*)`/g;
+const BACKREF = /\$(?:[0-9&'`]|<[A-Za-z_]\w*>)/;
+
+function offenders(text) {
+  const found = [];
+  for (const m of text.matchAll(STRING_REPLACEMENT)) {
+    const template = m[1];
+    if (!template.includes('${')) continue;
+    if (BACKREF.test(template.replace(/\$\{[^}]*\}/g, ''))) continue;
+    found.push(m[0].slice(0, 120));
+  }
+  return found;
+}
+
+test('no interpolated replace() replacement is passed as a string', () => {
+  const files = [...sourceFiles(path.join(ROOT, 'server')), ...sourceFiles(path.join(ROOT, 'vendor'))];
+  assert.ok(files.length > 50, `scanned ${files.length} files`);
+  const bad = [];
+  for (const file of files) {
+    for (const hit of offenders(fs.readFileSync(file, 'utf8'))) bad.push(`${path.relative(ROOT, file)}: ${hit}`);
+  }
+  assert.deepStrictEqual(bad, [], 'pass the replacement as () => `...` so $-sequences stay literal');
+});
+
+test('the guard catches the #332 form and allows the safe ones', () => {
+  assert.strictEqual(offenders("x.replace('</MediaVec>', `${el}\\n</MediaVec>`)").length, 1);
+  assert.strictEqual(offenders('x.replace(/<Name>[^<]*<\\/Name>/, `<Name>${n}</Name>`)').length, 1);
+  assert.strictEqual(offenders("x.replace('</MediaVec>', () => `${el}\\n</MediaVec>`)").length, 0);
+  assert.strictEqual(offenders('x.replace(/(<a>)<b\\/>/, `$1<b>${hex}</b>`)').length, 0);
+  assert.strictEqual(offenders("x.replace('a', 'b')").length, 0);
+});
+
+async function sequenceXml(buffer) {
+  const zip = await JSZip.loadAsync(buffer);
+  const parts = [];
+  for (const name of Object.keys(zip.files)) {
+    if (/SeqContainer\/[^/]+\.xml$|SeqContainer\d*\.xml$/.test(name)) parts.push(await zip.files[name].async('string'));
+  }
+  return parts.join('\n');
+}
+
+test('placeSubtitles keeps $-sequences in caption text', async () => {
+  const { buffer, startFrame } = await createEmptyProject({ timelineName: 'Subs' });
+  const res = await placeSubtitles(buffer, { subtitles: [{ startFrame, durationFrames: 48, text: TRICKY }] });
+  assert.ok((await sequenceXml(res.buffer)).includes(`<Name>${escapeXml(TRICKY)}</Name>`));
+});
+
+test('placeGenerator keeps $-sequences in the generator name', async () => {
+  const { buffer, startFrame } = await createEmptyProject({ timelineName: 'Gen' });
+  const res = await placeGenerator(buffer, { generatorName: TRICKY, trackIndex: 2, startFrame, durationFrames: 24 });
+  const xml = await sequenceXml(res.buffer);
+  assert.ok(xml.includes(`<PrettyType>${escapeXml(TRICKY)}</PrettyType>`));
+  assert.ok(xml.includes(`<Name>${escapeXml(TRICKY)}</Name>`));
+});
+
+test('placeFusionTitle keeps $-sequences in the clip name', async () => {
+  const { buffer, startFrame } = await createEmptyProject({ timelineName: 'Title' });
+  const res = await placeFusionTitle(buffer, { trackIndex: 2, startFrame, durationFrames: 24, name: TRICKY });
+  assert.ok((await sequenceXml(res.buffer)).includes(`<Name>${escapeXml(TRICKY)}</Name>`));
+});

package/resolve-advanced/vendor/drp-format/assemble-timeline.js

@@ -247,7 +247,7 @@ async function assembleTimeline(spec = {}) {
         if (!hit) throw new Error(`assembleTimeline: item markers — no ${kind} clip starting at ${cut.startFrame} on track ${cut.track ?? 1}`);
         const blob = encodeTimelineMarkersBlob(cut.markers);
         const el = `<Element>\n     <Sm2TiItemLockableBlob DbId="${randomUUID()}">\n      <FieldsBlob>${blob.toString('hex')}</FieldsBlob>\n      <BlobOwner>${hit[1]}</BlobOwner>\n      <DbSavedTime>0</DbSavedTime>\n     </Sm2TiItemLockableBlob>\n    </Element>\n   `;
-        pj = pj.replace('</LocableBlobSet>', `${el}</LocableBlobSet>`);
+        pj = pj.replace('</LocableBlobSet>', () => `${el}</LocableBlobSet>`);
       }
       zipIM.file('project.xml', pj);
       buffer = await zipIM.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
@@ -417,7 +417,7 @@ async function assembleTimeline(spec = {}) {
     const setM = pjX.match(/<LocableBlobSet>[\s\S]*?<\/LocableBlobSet>/);
     if (!setM) throw new Error('assembleTimeline: project.xml has no LocableBlobSet to hold markers');
     const el = `<Element>\n     <Sm2SequenceLockableBlob DbId="${randomUUID()}">\n      <FieldsBlob>${blob.toString('hex')}</FieldsBlob>\n      <BlobOwner>${seqIdM}</BlobOwner>\n      <DbSavedTime>0</DbSavedTime>\n     </Sm2SequenceLockableBlob>\n    </Element>\n   `;
-    pjX = pjX.replace('</LocableBlobSet>', `${el}</LocableBlobSet>`);
+    pjX = pjX.replace('</LocableBlobSet>', () => `${el}</LocableBlobSet>`);
     zipM.file('project.xml', pjX);
     buffer = await zipM.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
   }

package/resolve-advanced/vendor/drp-format/cut-media.js

@@ -27,6 +27,7 @@ const {
   emptyTrackClone,
 } = require('./seq-surgery');
 const { clipDbId, setClipStart, setClipDuration, setClipIn, setClipInEmpty } = require('./splice-clips');
+const { escapeXml } = require('./xml-builder');
 
 /**
  * @param {Buffer|string} drpInput
@@ -96,7 +97,7 @@ async function cutSourceIntoClips(drpInput, opts = {}) {
     if (cut.mediaRef) {
       // Multi-source: point this cut at ITS source's transplanted pool
       // element instead of the donor's.
-      c = c.replace(/<MediaRef>[0-9a-f-]{36}<\/MediaRef>/, `<MediaRef>${cut.mediaRef}</MediaRef>`);
+      c = c.replace(/<MediaRef>[0-9a-f-]{36}<\/MediaRef>/, () => `<MediaRef>${cut.mediaRef}</MediaRef>`);
     }
     if (cut.srcMeta && !native && cut.audioOnly) {
       // Every clone must carry ITS OWN source identity — a donor clone
@@ -106,15 +107,15 @@ async function cutSourceIntoClips(drpInput, opts = {}) {
       // A1 (measured, E15), and a TC-bearing video source fails the whole
       // render with "Full resolution media not found" (measured, E31).
       const { name, mediaFilePath, fps, frameCount } = cut.srcMeta;
-      c = c.replace(/<Name>[\s\S]*?<\/Name>/, `<Name>${name}</Name>`);
-      c = c.replace(/<MediaFilePath>[\s\S]*?<\/MediaFilePath>/, `<MediaFilePath>${mediaFilePath}</MediaFilePath>`);
+      c = c.replace(/<Name>[\s\S]*?<\/Name>/, () => `<Name>${escapeXml(name)}</Name>`);
+      c = c.replace(/<MediaFilePath>[\s\S]*?<\/MediaFilePath>/, () => `<MediaFilePath>${escapeXml(mediaFilePath)}</MediaFilePath>`);
       const rate = Buffer.alloc(16);
       rate.writeDoubleLE(fps, 0);
-      c = c.replace(/<MediaFrameRate>[0-9a-fA-F]*<\/MediaFrameRate>/, `<MediaFrameRate>${rate.toString('hex')}</MediaFrameRate>`);
+      c = c.replace(/<MediaFrameRate>[0-9a-fA-F]*<\/MediaFrameRate>/, () => `<MediaFrameRate>${rate.toString('hex')}</MediaFrameRate>`);
       const idm = Buffer.alloc(9);
       idm.writeUInt8(0x02, 0);
       idm.writeDoubleBE((frameCount - 1) / fps, 1);
-      c = c.replace(/<MediaTimemapBA>[0-9a-fA-F]*<\/MediaTimemapBA>/, `<MediaTimemapBA>${idm.toString('hex')}</MediaTimemapBA>`);
+      c = c.replace(/<MediaTimemapBA>[0-9a-fA-F]*<\/MediaTimemapBA>/, () => `<MediaTimemapBA>${idm.toString('hex')}</MediaTimemapBA>`);
       if (cut.audioOnly) {
         // Generic audio-clip FieldsBlob, verbatim from the live A2 harvest.
         // (Video clones keep their blob — repointClipBlobsInXml owns it.)
@@ -125,13 +126,13 @@ async function cutSourceIntoClips(drpInput, opts = {}) {
       // Embedded source timecode base, in SECONDS (harvested with the media
       // template). Donor default 0 makes Resolve seek the wrong TC and fail
       // the render with "Full resolution media not found at <TC>".
-      c = c.replace(/<MediaStartTime>[\s\S]*?<\/MediaStartTime>/, `<MediaStartTime>${cut.mediaStartTime}</MediaStartTime>`);
+      c = c.replace(/<MediaStartTime>[\s\S]*?<\/MediaStartTime>/, () => `<MediaStartTime>${cut.mediaStartTime}</MediaStartTime>`);
     }
     if (cut.timemap) {
       // Constant-speed retime: swap the identity MediaTimemapBA for the
       // caller-built Sm2TimeMap (r19 keyed form render/readback-verified;
       // the clip's <In>/<Duration> are RECORD-domain, measured live).
-      c = c.replace(/<MediaTimemapBA>[0-9a-fA-F]*<\/MediaTimemapBA>/, `<MediaTimemapBA>${cut.timemap}</MediaTimemapBA>`);
+      c = c.replace(/<MediaTimemapBA>[0-9a-fA-F]*<\/MediaTimemapBA>/, () => `<MediaTimemapBA>${cut.timemap}</MediaTimemapBA>`);
     }
     return c;
   };

package/resolve-advanced/vendor/drp-format/media-template-cache.js

@@ -59,11 +59,11 @@ function transplantMediaElement(mpXml, seqXmls, { poolElement, mediaRef }) {
   const folderId = (mpXml.slice(start, end).match(/<MpFolder>([0-9a-f-]{36})<\/MpFolder>/) || [])[1];
   let element = poolElement;
   if (folderId) {
-    element = element.replace(/<MpFolder>[0-9a-f-]{36}<\/MpFolder>/, `<MpFolder>${folderId}</MpFolder>`);
+    element = element.replace(/<MpFolder>[0-9a-f-]{36}<\/MpFolder>/, () => `<MpFolder>${folderId}</MpFolder>`);
   }
   const outMp = mpXml.slice(0, start) + element + mpXml.slice(end);
   const outSeqs = seqXmls.map((seq) =>
-    seq.replace(/<MediaRef>[0-9a-f-]{36}<\/MediaRef>/g, `<MediaRef>${mediaRef}</MediaRef>`),
+    seq.replace(/<MediaRef>[0-9a-f-]{36}<\/MediaRef>/g, () => `<MediaRef>${mediaRef}</MediaRef>`),
   );
   return { mpXml: outMp, seqXmls: outSeqs };
 }
@@ -75,7 +75,7 @@ function insertMediaElement(mpXml, poolElement) {
   const folderId = (mpXml.match(/<Sm2MpVideoClip[^>]*>[\s\S]*?<MpFolder>([0-9a-f-]{36})<\/MpFolder>/) || [])[1];
   let element = poolElement;
   if (folderId) {
-    element = element.replace(/<MpFolder>[0-9a-f-]{36}<\/MpFolder>/, `<MpFolder>${folderId}</MpFolder>`);
+    element = element.replace(/<MpFolder>[0-9a-f-]{36}<\/MpFolder>/, () => `<MpFolder>${folderId}</MpFolder>`);
   }
   return mpXml.slice(0, close) + element + mpXml.slice(close);
 }

package/resolve-advanced/vendor/drp-format/place-compound.js

@@ -72,22 +72,22 @@ async function placeCompound(drpInput, opts = {}) {
   //    the cuts machinery, 0-based frames).
   let inner = fs.readFileSync(T('compound-inner-r19.xml'), 'utf8');
   inner = freshDbIds(inner);
-  inner = inner.replace(/<Sm2SequenceContainer DbId="[^"]+"/, `<Sm2SequenceContainer DbId="${innerContainerId}"`);
-  inner = inner.replace(/<Sequence>[0-9a-f-]{36}<\/Sequence>/g, `<Sequence>${innerSequenceId}</Sequence>`);
+  inner = inner.replace(/<Sm2SequenceContainer DbId="[^"]+"/, () => `<Sm2SequenceContainer DbId="${innerContainerId}"`);
+  inner = inner.replace(/<Sequence>[0-9a-f-]{36}<\/Sequence>/g, () => `<Sequence>${innerSequenceId}</Sequence>`);
   inner = inner.replace(/<Items>[\s\S]*?<\/Items>/g, '<Items/>');
   zip.file(`SeqContainer/${innerContainerId}.xml`, inner);
 
   // 2) Pool compound element: fresh identities + blob SeqRef patch.
   let pool = fs.readFileSync(T('compound-pool-r19.xml'), 'utf8');
-  pool = pool.replace(/<Sm2MpCompoundClip DbId="[^"]+"/, `<Sm2MpCompoundClip DbId="${compoundId}"`);
-  pool = pool.replace(/<Sm2Sequence DbId="[^"]+"/, `<Sm2Sequence DbId="${innerSequenceId}"`);
-  pool = pool.replace(/<UniqueSequenceId>[^<]*<\/UniqueSequenceId>/, `<UniqueSequenceId>${crypto.randomUUID()}</UniqueSequenceId>`);
-  pool = pool.replace(/<UniqueMediaPoolItemId>[^<]*<\/UniqueMediaPoolItemId>/, `<UniqueMediaPoolItemId>${crypto.randomUUID()}</UniqueMediaPoolItemId>`);
-  pool = pool.replace(/<SmPTZRPreset DbId="[^"]+"/, `<SmPTZRPreset DbId="${crypto.randomUUID()}"`);
+  pool = pool.replace(/<Sm2MpCompoundClip DbId="[^"]+"/, () => `<Sm2MpCompoundClip DbId="${compoundId}"`);
+  pool = pool.replace(/<Sm2Sequence DbId="[^"]+"/, () => `<Sm2Sequence DbId="${innerSequenceId}"`);
+  pool = pool.replace(/<UniqueSequenceId>[^<]*<\/UniqueSequenceId>/, () => `<UniqueSequenceId>${crypto.randomUUID()}</UniqueSequenceId>`);
+  pool = pool.replace(/<UniqueMediaPoolItemId>[^<]*<\/UniqueMediaPoolItemId>/, () => `<UniqueMediaPoolItemId>${crypto.randomUUID()}</UniqueMediaPoolItemId>`);
+  pool = pool.replace(/<SmPTZRPreset DbId="[^"]+"/, () => `<SmPTZRPreset DbId="${crypto.randomUUID()}"`);
   // The embedded sequence's <Parent> points BACK at the compound's own id —
   // the reference sweep found it as the one un-rewired link (a dangling
   // Parent is presumably as fatal as the dangling MpFolder/SeqRef were).
-  pool = pool.replace(/<Parent>[0-9a-f-]{36}<\/Parent>/, `<Parent>${compoundId}</Parent>`);
+  pool = pool.replace(/<Parent>[0-9a-f-]{36}<\/Parent>/, () => `<Parent>${compoundId}</Parent>`);
   {
     const fbM = pool.match(/(<Sm2Sequence DbId="[^"]+">\s*<FieldsBlob>)([0-9a-fA-F]+)(<\/FieldsBlob>)/);
     if (!fbM) throw new Error('placeCompound: embedded Sm2Sequence FieldsBlob not found');
@@ -98,12 +98,12 @@ async function placeCompound(drpInput, opts = {}) {
     const patched = encodeKeyedDict({ hdr: dict.hdr, entries: dict.entries }).toString('hex');
     pool = pool.replace(fbM[0], `${fbM[1]}${patched}${fbM[3]}`);
   }
-  pool = pool.replace(/<Name>[^<]*<\/Name>/, `<Name>${escapeXml(name)}</Name>`);
+  pool = pool.replace(/<Name>[^<]*<\/Name>/, () => `<Name>${escapeXml(name)}</Name>`);
   // MediaExtents = [startSec, durationSec] LE doubles; inner starts at 0.
   const me = Buffer.alloc(16);
   me.writeDoubleLE(0, 0);
   me.writeDoubleLE(durationFrames / fps, 8);
-  pool = pool.replace(/<MediaExtents>[0-9a-fA-F]*<\/MediaExtents>/, `<MediaExtents>${me.toString('hex')}</MediaExtents>`);
+  pool = pool.replace(/<MediaExtents>[0-9a-fA-F]*<\/MediaExtents>/, () => `<MediaExtents>${me.toString('hex')}</MediaExtents>`);
   // Attach to the primary MediaPool folder — and point the element's
   // <MpFolder> at THAT folder's DbId (the template's value references the
   // harvest project's folder; a dangling folder ref CRASHES Resolve on
@@ -112,22 +112,22 @@ async function placeCompound(drpInput, opts = {}) {
   let mpXml = await zip.file(mpPath).async('string');
   const folderId = (mpXml.match(/<Sm2MpFolder DbId="([^"]+)"/) || [])[1];
   if (!folderId) throw new Error('placeCompound: target MpFolder has no Sm2MpFolder DbId');
-  pool = pool.replace(/<MpFolder>[0-9a-f-]{36}<\/MpFolder>/, `<MpFolder>${folderId}</MpFolder>`);
-  mpXml = mpXml.replace('</MediaVec>', `${pool}\n  </MediaVec>`);
+  pool = pool.replace(/<MpFolder>[0-9a-f-]{36}<\/MpFolder>/, () => `<MpFolder>${folderId}</MpFolder>`);
+  mpXml = mpXml.replace('</MediaVec>', () => `${pool}\n  </MediaVec>`);
   zip.file(mpPath, mpXml);
 
   // 3) Parent item: template clone → fresh id, name, placement, MediaRef,
   //    identity timemap over the inner content ((frames − 0.5)/fps, measured).
   let item = fs.readFileSync(T('compound-item-r19.xml'), 'utf8').trim();
   item = freshDbIds(item);
-  item = item.replace(/<Name>[^<]*<\/Name>/, `<Name>${escapeXml(name)}</Name>`);
-  item = item.replace(/<Start>\d+<\/Start>/, `<Start>${startFrame}</Start>`);
-  item = item.replace(/<Duration>\d+<\/Duration>/, `<Duration>${durationFrames}</Duration>`);
-  item = item.replace(/<MediaRef>[0-9a-f-]{36}<\/MediaRef>/, `<MediaRef>${compoundId}</MediaRef>`);
+  item = item.replace(/<Name>[^<]*<\/Name>/, () => `<Name>${escapeXml(name)}</Name>`);
+  item = item.replace(/<Start>\d+<\/Start>/, () => `<Start>${startFrame}</Start>`);
+  item = item.replace(/<Duration>\d+<\/Duration>/, () => `<Duration>${durationFrames}</Duration>`);
+  item = item.replace(/<MediaRef>[0-9a-f-]{36}<\/MediaRef>/, () => `<MediaRef>${compoundId}</MediaRef>`);
   const tm = Buffer.alloc(9);
   tm.writeUInt8(0x02, 0);
   tm.writeDoubleBE((durationFrames - 0.5) / fps, 1);
-  item = item.replace(/<MediaTimemapBA>[0-9a-fA-F]*<\/MediaTimemapBA>/, `<MediaTimemapBA>${tm.toString('hex')}</MediaTimemapBA>`);
+  item = item.replace(/<MediaTimemapBA>[0-9a-fA-F]*<\/MediaTimemapBA>/, () => `<MediaTimemapBA>${tm.toString('hex')}</MediaTimemapBA>`);
 
   const { match: vec, tracks } = getTrackVec(parentXml, 'video');
   if (track > tracks.length) throw new Error(`placeCompound: parent video track ${track} does not exist (${tracks.length})`);

package/resolve-advanced/vendor/drp-format/place-fusion-title.js

@@ -96,9 +96,9 @@ async function placeFusionTitle(drpInput, opts = {}) {
     throw new Error('placeFusionTitle: template is not a Fusion Title clip');
   }
   clip = freshDbIds(clip);
-  clip = clip.replace(/<Start>\d+<\/Start>/, `<Start>${startFrame}</Start>`);
-  clip = clip.replace(/<Duration>\d+<\/Duration>/, `<Duration>${durationFrames}</Duration>`);
-  if (name) clip = clip.replace(/<Name>[\s\S]*?<\/Name>/, `<Name>${escapeXml(name)}</Name>`);
+  clip = clip.replace(/<Start>\d+<\/Start>/, () => `<Start>${startFrame}</Start>`);
+  clip = clip.replace(/<Duration>\d+<\/Duration>/, () => `<Duration>${durationFrames}</Duration>`);
+  if (name) clip = clip.replace(/<Name>[\s\S]*?<\/Name>/, () => `<Name>${escapeXml(name)}</Name>`);
   const titleInputs = { text, font, style, size, vJustify, hJustify, color };
   if (Object.values(titleInputs).some((v) => v !== undefined && v !== null)) {
     const m = clip.match(/<CompositionBA>([0-9a-fA-F]*)<\/CompositionBA>/);

package/resolve-advanced/vendor/drp-format/place-generator.js

@@ -75,17 +75,17 @@ async function placeGenerator(drpInput, opts = {}) {
 
   let gen = fs.readFileSync(snippetPathFor(templateVersion), 'utf8').trim();
   gen = freshDbIds(gen);
-  gen = gen.replace(/<PrettyType>[\s\S]*?<\/PrettyType>/, `<PrettyType>${escapeXml(generatorName)}</PrettyType>`);
-  gen = gen.replace(/<Name>[\s\S]*?<\/Name>/, `<Name>${escapeXml(generatorName)}</Name>`);
-  gen = gen.replace(/<Start>\d+<\/Start>/, `<Start>${startFrame}</Start>`);
-  gen = gen.replace(/<Duration>\d+<\/Duration>/, `<Duration>${durationFrames}</Duration>`);
+  gen = gen.replace(/<PrettyType>[\s\S]*?<\/PrettyType>/, () => `<PrettyType>${escapeXml(generatorName)}</PrettyType>`);
+  gen = gen.replace(/<Name>[\s\S]*?<\/Name>/, () => `<Name>${escapeXml(generatorName)}</Name>`);
+  gen = gen.replace(/<Start>\d+<\/Start>/, () => `<Start>${startFrame}</Start>`);
+  gen = gen.replace(/<Duration>\d+<\/Duration>/, () => `<Duration>${durationFrames}</Duration>`);
   const colorNorm = color != null ? normalizeColor(color) : null;
   if (colorNorm) {
     const blob = solidColorEffectBlob(colorNorm);
     if (!/<EffectFiltersBA\s*\/>|<EffectFiltersBA>\s*<\/EffectFiltersBA>/.test(gen)) {
       throw new Error('placeGenerator: template carries no empty <EffectFiltersBA/> to populate with the colour');
     }
-    gen = gen.replace(/<EffectFiltersBA\s*\/>|<EffectFiltersBA>\s*<\/EffectFiltersBA>/, `<EffectFiltersBA>${blob}</EffectFiltersBA>`);
+    gen = gen.replace(/<EffectFiltersBA\s*\/>|<EffectFiltersBA>\s*<\/EffectFiltersBA>/, () => `<EffectFiltersBA>${blob}</EffectFiltersBA>`);
   }
 
   const { match: vtv, tracks } = getTrackVec(seqXml, 'video');

package/resolve-advanced/vendor/drp-format/place-subtitles.js

@@ -94,9 +94,9 @@ async function placeSubtitles(drpInput, opts = {}) {
     '    <UserDefinedName/>\n    <LayersVec/>\n   </Sm2TiTrack>\n  </Element>\n ';
   let xml;
   if (/<SubtitleTrackVec\/>/.test(seqXml)) {
-    xml = seqXml.replace('<SubtitleTrackVec/>', `<SubtitleTrackVec>${track}</SubtitleTrackVec>`);
+    xml = seqXml.replace('<SubtitleTrackVec/>', () => `<SubtitleTrackVec>${track}</SubtitleTrackVec>`);
   } else if (/<SubtitleTrackVec>/.test(seqXml)) {
-    xml = seqXml.replace('</SubtitleTrackVec>', `${track}</SubtitleTrackVec>`);
+    xml = seqXml.replace('</SubtitleTrackVec>', () => `${track}</SubtitleTrackVec>`);
   } else {
     throw new Error('placeSubtitles: timeline has no SubtitleTrackVec');
   }

package/resolve-advanced/vendor/drp-format/place-transition.js

@@ -115,9 +115,9 @@ async function placeTransition(drpInput, opts = {}) {
   let trans = fs.readFileSync(trackType === 'audio' ? AUDIO_TEMPLATE_PATH : TEMPLATE_PATH, 'utf8').trim();
   trans = freshDbIds(trans);
   if (type === 'wipe') {
-    trans = trans.replace(/<FieldsBlob>[0-9a-fA-F]*<\/FieldsBlob>/, `<FieldsBlob>${WIPE_FIELDS_BLOB}</FieldsBlob>`);
+    trans = trans.replace(/<FieldsBlob>[0-9a-fA-F]*<\/FieldsBlob>/, () => `<FieldsBlob>${WIPE_FIELDS_BLOB}</FieldsBlob>`);
   } else if (STYLE_PRETTY_TYPES[type]) {
-    trans = trans.replace(/<PrettyType>Cross Dissolve<\/PrettyType>/, `<PrettyType>${STYLE_PRETTY_TYPES[type]}</PrettyType>`);
+    trans = trans.replace(/<PrettyType>Cross Dissolve<\/PrettyType>/, () => `<PrettyType>${STYLE_PRETTY_TYPES[type]}</PrettyType>`);
   }
   // Span geometry follows <Start>/<Duration>, NOT AlignmentType (the E61
   // harvest of Resolve's own EDL import carries AlignmentType 2 with the
@@ -132,8 +132,8 @@ async function placeTransition(drpInput, opts = {}) {
     }
   }
   const start = spanStart !== undefined ? spanStart : atFrame - Math.floor(durationFrames / 2);
-  trans = trans.replace(/<Start>\d+<\/Start>/, `<Start>${start}</Start>`);
-  trans = trans.replace(/<Duration>\d+<\/Duration>/, `<Duration>${durationFrames}</Duration>`);
+  trans = trans.replace(/<Start>\d+<\/Start>/, () => `<Start>${start}</Start>`);
+  trans = trans.replace(/<Duration>\d+<\/Duration>/, () => `<Duration>${durationFrames}</Duration>`);
   const transitionDbId = (trans.match(/<Sm2TiTransition DbId="([^"]+)"/) || [])[1] || null;
 
   // Insert the transition <Element> immediately after the left clip's <Element> in <Items>.

package/resolve-advanced/vendor/drp-format/seq-surgery.js

@@ -89,7 +89,7 @@ function getItemsInner(trackElement) {
 function setItemsInner(trackElement, inner) {
   const body = inner && inner.trim() ? inner : null;
   if (/<Items\s*\/>/.test(trackElement)) {
-    return body ? trackElement.replace(/<Items\s*\/>/, `<Items>${body}</Items>`) : trackElement;
+    return body ? trackElement.replace(/<Items\s*\/>/, () => `<Items>${body}</Items>`) : trackElement;
   }
   return trackElement.replace(/<Items>[\s\S]*?<\/Items>/, body ? `<Items>${body}</Items>` : '<Items/>');
 }

package/resolve-advanced/vendor/drp-format/splice-clips.js

@@ -37,10 +37,10 @@ function clipDuration(clipXml) {
   return m ? parseInt(m[1], 10) : null;
 }
 function setClipStart(clipXml, v) {
-  return clipXml.replace(/<Start>\d+<\/Start>/, `<Start>${v}</Start>`);
+  return clipXml.replace(/<Start>\d+<\/Start>/, () => `<Start>${v}</Start>`);
 }
 function setClipDuration(clipXml, v) {
-  return clipXml.replace(/<Duration>\d+<\/Duration>/, `<Duration>${v}</Duration>`);
+  return clipXml.replace(/<Duration>\d+<\/Duration>/, () => `<Duration>${v}</Duration>`);
 }
 // The source IN-point lives in <In> as `<framePos>|<LE-double of framePos*0.001>`, where framePos
 // is in TIMELINE frames (verified live: Resolve appended a clip with source-in 600 media-frames @29.97
@@ -143,7 +143,7 @@ async function moveClip(drpInput, opts = {}) {
   // Optionally retime.
   if (toStart !== undefined && toStart !== null) {
     if (!Number.isInteger(toStart)) throw new TypeError('moveClip: toStart must be an integer');
-    clip = clip.replace(/<Start>\d+<\/Start>/, `<Start>${toStart}</Start>`);
+    clip = clip.replace(/<Start>\d+<\/Start>/, () => `<Start>${toStart}</Start>`);
   }
 
   // Grow to the destination track with empty clones, then insert.

package/scripts/edit_subtitle_timeline.mjs

@@ -1,11 +1,12 @@
 // Structured stdin bridge used by the live Python server.
-import { editSubtitleTimeline, inspectSubtitleTimeline } from '../resolve-advanced/server/subtitle-timeline.mjs';
+import { editSubtitleTimeline, inspectSubtitleTimeline, editCaptionTimeline, inspectCaptionTimeline }
+  from '../resolve-advanced/server/subtitle-timeline.mjs';
+const operations = { inspect: inspectSubtitleTimeline, inspect_captions: inspectCaptionTimeline, write_captions: editCaptionTimeline };
 try {
   let input = '';
   for await (const chunk of process.stdin) input += chunk;
-  const request = JSON.parse(input);
-  process.stdout.write(JSON.stringify(await (request.operation === 'inspect'
-    ? inspectSubtitleTimeline(request) : editSubtitleTimeline(request))));
+  const { operation, ...request } = JSON.parse(input);
+  process.stdout.write(JSON.stringify(await (operations[operation] || editSubtitleTimeline)(request)));
 } catch (error) {
   process.stderr.write(error.message);
   process.exitCode = 1;

package/src/granular/common.py

@@ -92,7 +92,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.17.1"
+VERSION = "4.18.1"
 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 377-tool granular server instead
 """
 
-VERSION = "4.17.1"
+VERSION = "4.18.1"
 
 import base64
 import os
@@ -52,6 +52,8 @@ from src.utils.resolve211_alignment import auto_align
 from src.utils.resolve211_dctl import native_dctl_result
 from src.utils.resolve211_normalization import normalize_audio
 from src.utils.subtitle_live import set_subtitle_preset as _set_live_subtitle_preset
+from src.utils.subtitle_live import list_captions_live as _list_live_captions
+from src.utils.subtitle_live import write_captions_live as _write_live_captions
 from src.utils.title_library import list_title_presets as _list_installed_title_presets
 from src.utils.title_controls import title_text_targets as _title_text_targets
 from src.utils.title_controls import title_text_keys as _title_text_keys
@@ -13355,7 +13357,9 @@ def _media_analysis_replace_owned_block(existing: Any, body: Any) -> str:
         + re.escape(_MCP_METADATA_BLOCK_END)
     )
     if re.search(pattern, existing_text, flags=re.DOTALL):
-        return re.sub(pattern, block, existing_text, flags=re.DOTALL).strip()
+        # A function replacement inserts the block literally: as a string, a
+        # backslash in the analysis text (a Windows path) is read as an escape.
+        return re.sub(pattern, lambda _match: block, existing_text, flags=re.DOTALL).strip()
     return f"{existing_text}\n\n{block}".strip() if existing_text else block
 
 
@@ -28814,6 +28818,16 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         inspect rendered frames separately. Successful staging exports are removed;
         failure results report retained staging for diagnosis. Unbundled dry runs need an
         existing preset_reference to avoid live capture. Never patches Project.db.
+      list_captions_live(track?) -> {fps, captions:[{id,text,start,end,words}]}  — decoded
+        from a native DRT export (timeline frames); read-only, Resolve stays open.
+      write_captions_live(track?, replace?, add?, delete?, template_caption_id?, revision_name?, dry_run?)
+        Same caption shape as advanced project_db write_captions, but with Resolve open:
+        replace:[{id,text,start,end,words:[{text,start,end}]}], add:[{text,start,end,words}],
+        delete:[id]. text = words joined by spaces; words must tile the caption.
+        id = the caption start frame as a string (Resolve re-mints item IDs per export).
+        Native export -> caption codec -> native import as a selected revision;
+        Resolve's re-export is decoded and must match text, bounds and word frames.
+        Original retained and re-selected on failure. Never patches Project.db.
       detect_scene_cuts(background?) -> {success | job_id}
       analyze_dolby_vision(clip_ids?, analysis_type?, background?) -> {success | job_id}
       grab_still() -> {success}
@@ -28837,6 +28851,11 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
         # Match the safety decorator's boolean interpretation before any capture/import.
         return _set_live_subtitle_preset(get_resolve(), proj, tl,
                                         {**p, "dry_run": _coerce_bool(p.get("dry_run", p.get("dryRun")))}, _resolve_safe_dir)
+    elif action == "list_captions_live":
+        return _list_live_captions(get_resolve(), tl, p, _resolve_safe_dir)
+    elif action == "write_captions_live":
+        return _write_live_captions(get_resolve(), proj, tl,
+                                    {**p, "dry_run": _coerce_bool(p.get("dry_run", p.get("dryRun")))}, _resolve_safe_dir)
     elif action == "detect_scene_cuts":
         return _run_maybe_background(
             "timeline_ai.detect_scene_cuts", p, lambda: {"success": bool(tl.DetectSceneCuts())}
@@ -28861,7 +28880,7 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
     elif action == "grab_all_stills":
         stills = tl.GrabAllStills(p.get("source", 1))
         return {"count": len(stills) if stills else 0}
-    return _unknown(action, ["list_title_presets","create_subtitles","set_subtitle_preset","detect_scene_cuts","analyze_dolby_vision","grab_still","grab_all_stills"])
+    return _unknown(action, ["list_title_presets","create_subtitles","set_subtitle_preset","list_captions_live","write_captions_live","detect_scene_cuts","analyze_dolby_vision","grab_still","grab_all_stills"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════

package/src/utils/destructive_hook.py

@@ -192,6 +192,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "analyze_dolby_vision",
         "create_subtitles",
         "set_subtitle_preset",
+        "write_captions_live",
     }),
     "timeline_item": frozenset({
         "delete_keyframe",
@@ -378,6 +379,7 @@ NATIVE_DRY_RUN_ACTIONS: frozenset = frozenset({
     ("timeline", "replace_source_range"),
     ("timeline_ai", "create_subtitles"),
     ("timeline_ai", "set_subtitle_preset"),
+    ("timeline_ai", "write_captions_live"),
     ("script_plugin", "safe_install_extension"),
     ("script_plugin", "safe_remove_extension"),
     ("project_manager", "safe_project_delete"),

package/src/utils/execution_lifecycle.py

@@ -347,6 +347,7 @@ class RiskClassificationHook(LifecycleHook):
         # Analysis passes that write their results back onto the timeline.
         ("timeline_ai", "create_subtitles"),
         ("timeline_ai", "set_subtitle_preset"),
+        ("timeline_ai", "write_captions_live"),
         ("timeline_ai", "analyze_dolby_vision"),
         # Grade state that is replaced rather than removed. AddVersion also
         # switches the active version, so a later graph write lands on the new

package/src/utils/subtitle_live.py

@@ -74,12 +74,19 @@ def _capture_installed_preset(resolve, project, preset, output):
             raise RuntimeError(f"Preset capture cleanup refused; retained {capture.GetName()}")
 
 
-def _inventory(timeline):
-    """Compare track counts and item names, bounds and media IDs only."""
+def _inventory(timeline, edited_subtitle_track=None):
+    """Compare track counts and item names, bounds and media IDs only.
+
+    edited_subtitle_track is left out of the comparison when a call rewrites its
+    captions; those are verified by decoding the re-export instead.
+    """
     result = {}
     for kind in ("video", "audio", "subtitle"):
         tracks = []
         for index in range(1, int(timeline.GetTrackCount(kind) or 0) + 1):
+            if kind == "subtitle" and index == edited_subtitle_track:
+                tracks.append("edited")
+                continue
             items = []
             for item in timeline.GetItemListInTrack(kind, index) or []:
                 media = item.GetMediaPoolItem()
@@ -90,8 +97,23 @@ def _inventory(timeline):
     return result
 
 
-def set_subtitle_preset(resolve, project, timeline, params, safe_dir):
-    """Create and select a verified revision; restore original on any failure."""
+def _codec(node, request, default_error="Subtitle codec failed"):
+    """Run one bridge operation and return its decoded JSON result."""
+    completed = subprocess.run([node, str(BRIDGE)], input=json.dumps(request),
+                               capture_output=True, text=True, encoding="utf-8", errors="replace",
+                               timeout=60, check=False)
+    if completed.returncode:
+        err = completed.stderr.strip() or default_error
+        if "ERR_MODULE_NOT_FOUND" in err or "Cannot find package" in err:
+            err = subtitle_codec_gap() or (
+                f"{err} From {_ADVANCED} run: npm install --omit=dev --omit=optional"
+            )
+        raise RuntimeError(err)
+    return json.loads(completed.stdout)
+
+
+def _preflight(timeline, params):
+    """Shared argument checks: (node, dry_run, track), or an error result."""
     node = shutil.which("node")
     if not node:
         return {"success": False, "error": "Node.js is required for the subtitle preset codec"}
@@ -102,23 +124,16 @@ def set_subtitle_preset(resolve, project, timeline, params, safe_dir):
     dry_run = params.get("dry_run", False)
     if not isinstance(dry_run, bool):
         return {"success": False, "error": "dry_run must be coerced to a boolean by the dispatcher"}
-    inputs = params.get("inputs", {})
-    if not isinstance(inputs, dict):
-        return {"success": False, "error": "inputs must be an object"}
     track = params.get("track", 1)
     if isinstance(track, bool) or not isinstance(track, int) or not 1 <= track <= timeline.GetTrackCount("subtitle"):
         return {"success": False, "error": "Subtitle track index out of range"}
-    reference = params.get("preset_reference")
-    if reference and not Path(reference).is_file():
-        return {"success": False, "error": "preset_reference must be an existing native DRT export"}
-    installed = None
-    if params.get("preset") not in (None, "Word Highlight", "Lollipop") and not reference:
-        try:
-            installed = find_subtitle_preset(params["preset"], params.get("templates_archive"))
-        except (OSError, ValueError) as exc:
-            return {"success": False, "error": str(exc)}
-        if dry_run:
-            return {"success": False, "error": "Uncached installed preset capture needs a live temporary timeline; use preset_reference for a mutation-free dry run"}
+    return node, dry_run, track
+
+
+def _revise(resolve, project, timeline, params, safe_dir, *, dry_run, build, check, report, edited_track=None):
+    """Export, build(source, output, staging) a patched DRT, import it as a selected
+    revision and check(readback, patch) Resolve's re-export of it. The original is
+    never modified and stays active on any failure or preview."""
     name = params.get("revision_name") or f"{timeline.GetName()} - subtitles {uuid.uuid4().hex[:8]}"
     if any(project.GetTimelineByIndex(i).GetName() == name for i in range(1, project.GetTimelineCount() + 1)):
         return {"success": False, "error": "revision_name already exists"}
@@ -127,33 +142,14 @@ def set_subtitle_preset(resolve, project, timeline, params, safe_dir):
     source, output = staging / "original.drt", staging / "revision.drt"
     original_active = project.GetCurrentTimeline()
     original_timecode = timeline.GetCurrentTimecode()
-    before = _inventory(timeline)
+    before = _inventory(timeline, edited_track)
     imported = None
     succeeded = False
     result = None
     try:
         if not timeline.Export(str(source), resolve.EXPORT_DRT):
             raise RuntimeError("Native timeline export failed")
-        request = {"source": str(source), "output": str(output), "track": track, "inputs": inputs}
-        if installed:
-            captured = staging / "installed-title.drt"
-            _capture_installed_preset(resolve, project, installed, captured)
-            request.update(title_reference=str(captured), template_id=installed["template_id"])
-        if reference:
-            request.update(preset_reference=os.path.abspath(reference), reference_track=params.get("reference_track", 1))
-        if params.get("preset") and not reference:
-            request["preset"] = params["preset"]
-        completed = subprocess.run([node, str(BRIDGE)], input=json.dumps(request),
-                                   capture_output=True, text=True, encoding="utf-8", errors="replace",
-                                   timeout=60, check=False)
-        if completed.returncode:
-            err = completed.stderr.strip() or "Subtitle codec failed"
-            if "ERR_MODULE_NOT_FOUND" in err or "Cannot find package" in err:
-                err = subtitle_codec_gap() or (
-                    f"{err} From {_ADVANCED} run: npm install --omit=dev --omit=optional"
-                )
-            raise RuntimeError(err)
-        patch = json.loads(completed.stdout)
+        patch = build(source, output, staging)
         # The codec's output file is private staging, removed after success.
         patch.pop("output", None)
         if dry_run:
@@ -164,26 +160,18 @@ def set_subtitle_preset(resolve, project, timeline, params, safe_dir):
         imported = project.GetMediaPool().ImportTimelineFromFile(str(output), {"importSourceClips": False})
         if not imported:
             raise RuntimeError("Resolve refused the patched native timeline")
-        if _inventory(imported) != before:
+        if _inventory(imported, edited_track) != before:
             raise RuntimeError("Imported edit differs in track counts, clip/caption names, bounds or media IDs")
         if not imported.SetName(name):
             raise RuntimeError("Failed to name subtitle revision")
         if imported.GetName() != name:
             raise RuntimeError("Subtitle revision name did not persist")
         # Re-export through Resolve to prove that it parsed and retained the
-        # preset. The codec's own pre-import readback alone is insufficient.
+        # edit. The codec's own pre-import readback alone is insufficient.
         readback = staging / "resolve-readback.drt"
         if not imported.Export(str(readback), resolve.EXPORT_DRT):
             raise RuntimeError("Failed to re-export the imported subtitle revision")
-        checked = subprocess.run([node, str(BRIDGE)],
-                                 input=json.dumps({"operation": "inspect", "source": str(readback), "track": track}),
-                                 capture_output=True, text=True, encoding="utf-8", errors="replace",
-                                 timeout=60, check=False)
-        if checked.returncode:
-            raise RuntimeError(checked.stderr.strip() or "Imported preset readback failed")
-        actual = json.loads(checked.stdout)
-        if actual.get("templateId") != patch.get("templateId") or actual.get("inputs") != patch.get("after"):
-            raise RuntimeError("Resolve did not retain the requested subtitle controls")
+        check(readback, patch)
         selected, detail = set_current_timeline(project, imported)
         if not selected:
             raise RuntimeError(describe_switch_failure(detail, "selecting subtitle revision"))
@@ -193,12 +181,8 @@ def set_subtitle_preset(resolve, project, timeline, params, safe_dir):
                 warnings.append("Subtitle revision was selected, but its playhead could not be restored")
         succeeded = True
         result = {"success": True, "restart_required": False, "original_timeline": timeline.GetName(),
-                "timeline": imported.GetName(), "timeline_id": imported.GetUniqueId(),
-                "patch": patch,
-                "verification": "resolve_reexport_preset_readback_and_live_edit_inventory",
-                "verified_components": ["track_counts", "item_names", "item_bounds", "media_ids", "subtitle_preset_controls"],
-                "unverified_components": ["markers", "grades", "other_fusion_compositions", "audio_content"],
-                "render_verified": False}
+                  "timeline": imported.GetName(), "timeline_id": imported.GetUniqueId(),
+                  "patch": patch, **report, "render_verified": False}
         if warnings:
             result["warnings"] = warnings
         return result
@@ -231,3 +215,112 @@ def set_subtitle_preset(resolve, project, timeline, params, safe_dir):
             else:
                 result["staging_retained"] = True
                 result["staging_directory"] = str(staging)
+
+
+def set_subtitle_preset(resolve, project, timeline, params, safe_dir):
+    """Create and select a verified revision; restore original on any failure."""
+    checked = _preflight(timeline, params)
+    if isinstance(checked, dict):
+        return checked
+    node, dry_run, track = checked
+    inputs = params.get("inputs", {})
+    if not isinstance(inputs, dict):
+        return {"success": False, "error": "inputs must be an object"}
+    reference = params.get("preset_reference")
+    if reference and not Path(reference).is_file():
+        return {"success": False, "error": "preset_reference must be an existing native DRT export"}
+    installed = None
+    if params.get("preset") not in (None, "Word Highlight", "Lollipop") and not reference:
+        try:
+            installed = find_subtitle_preset(params["preset"], params.get("templates_archive"))
+        except (OSError, ValueError) as exc:
+            return {"success": False, "error": str(exc)}
+        if dry_run:
+            return {"success": False, "error": "Uncached installed preset capture needs a live temporary timeline; use preset_reference for a mutation-free dry run"}
+
+    def build(source, output, staging):
+        request = {"source": str(source), "output": str(output), "track": track, "inputs": inputs}
+        if installed:
+            captured = staging / "installed-title.drt"
+            _capture_installed_preset(resolve, project, installed, captured)
+            request.update(title_reference=str(captured), template_id=installed["template_id"])
+        if reference:
+            request.update(preset_reference=os.path.abspath(reference), reference_track=params.get("reference_track", 1))
+        if params.get("preset") and not reference:
+            request["preset"] = params["preset"]
+        return _codec(node, request)
+
+    def check(readback, patch):
+        actual = _codec(node, {"operation": "inspect", "source": str(readback), "track": track},
+                        "Imported preset readback failed")
+        if actual.get("templateId") != patch.get("templateId") or actual.get("inputs") != patch.get("after"):
+            raise RuntimeError("Resolve did not retain the requested subtitle controls")
+
+    return _revise(resolve, project, timeline, params, safe_dir, dry_run=dry_run, build=build, check=check, report={
+        "verification": "resolve_reexport_preset_readback_and_live_edit_inventory",
+        "verified_components": ["track_counts", "item_names", "item_bounds", "media_ids", "subtitle_preset_controls"],
+        "unverified_components": ["markers", "grades", "other_fusion_compositions", "audio_content"]})
+
+
+def _caption_shape(captions):
+    """What a caption write must preserve. Item IDs are remapped on import."""
+    return [{"text": c["text"], "start": c["start"], "end": c["end"],
+             "words": [(w["text"], w["start"], w["end"]) for w in c["words"]]} for c in captions]
+
+
+def list_captions_live(resolve, timeline, params, safe_dir):
+    """Decode one subtitle track's captions from a native export; mutates nothing."""
+    checked = _preflight(timeline, {**params, "dry_run": False})
+    if isinstance(checked, dict):
+        return checked
+    node, _, track = checked
+    staging = Path(safe_dir(str(ROOT / "logs" / "subtitle-live"))) / uuid.uuid4().hex
+    staging.mkdir(parents=True, exist_ok=False)
+    try:
+        source = staging / "original.drt"
+        if not timeline.Export(str(source), resolve.EXPORT_DRT):
+            return {"success": False, "error": "Native timeline export failed"}
+        return {"success": True, "timeline": timeline.GetName(),
+                **_codec(node, {"operation": "inspect_captions", "source": str(source), "track": track})}
+    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError) as exc:
+        return {"success": False, "error": str(exc)}
+    finally:
+        # This UUID directory belongs only to this read.
+        shutil.rmtree(staging, ignore_errors=True)
+
+
+def write_captions_live(resolve, project, timeline, params, safe_dir):
+    """Replace/add/delete caption text and word timing as a verified revision, Resolve open.
+
+    Same caption shape as advanced project_db write_captions (timeline frames, words
+    tile each caption). A caption id is its start frame as a string, as list_captions_live
+    reports it: Resolve issues fresh item IDs on every export.
+    """
+    checked = _preflight(timeline, params)
+    if isinstance(checked, dict):
+        return checked
+    node, dry_run, track = checked
+    edits = {key: params.get(key, []) for key in ("replace", "add", "delete")}
+    if not all(isinstance(value, list) for value in edits.values()):
+        return {"success": False, "error": "replace, add and delete must be lists"}
+    template = params.get("template_caption_id", params.get("templateCaptionId"))
+
+    def build(source, output, staging):
+        request = {"operation": "write_captions", "source": str(source), "output": str(output),
+                   "track": track, **edits}
+        if template:
+            request["templateCaptionId"] = template
+        return _codec(node, request)
+
+    def check(readback, patch):
+        actual = _codec(node, {"operation": "inspect_captions", "source": str(readback), "track": track},
+                        "Imported caption readback failed")
+        if _caption_shape(actual.get("captions", [])) != _caption_shape(patch.get("captions", [])):
+            raise RuntimeError("Resolve did not retain the requested caption text or word timing")
+
+    return _revise(resolve, project, timeline, params, safe_dir, dry_run=dry_run, build=build, check=check,
+                   edited_track=track, report={
+                       "verification": "resolve_reexport_caption_readback_and_live_edit_inventory",
+                       "verified_components": ["track_counts", "item_names", "item_bounds", "media_ids",
+                                               "caption_text", "caption_bounds", "word_timing"],
+                       "unverified_components": ["markers", "grades", "fusion_compositions", "audio_content"]})