davinci-resolve-mcp 4.17.1 → 4.18.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 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.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.0-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.0-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.0 版 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.0"
 # 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.0",
   "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/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.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "4.17.1"
+VERSION = "4.18.0"
 
 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
@@ -28814,6 +28816,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 +28849,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 +28878,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"]})