davinci-resolve-mcp 4.9.3 → 4.10.0

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 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.10.0 — subtitle caption and preset editing in saved projects
+
+### Added
+
+- **Subtitle editing through `project_db`.** Resolve's scripting API can
+  generate and list subtitles but cannot change caption text, word timing or
+  a track's animation controls (`TimelineItem.SetProperty` does not reach
+  them). Six new actions edit them in a saved local project's `Project.db`:
+  - `list_captions`, `check_captions` and `write_captions`: caption text,
+    frame bounds and explicit per-word timing; add, replace and delete in one
+    transaction, preserving unknown fields and the original AI words.
+  - `list_subtitle_presets`, `copy_subtitle_preset` and
+    `set_subtitle_preset`: clone a compatible saved animation preset, and edit
+    Word Highlight's font, position, text / highlight / outline colours and
+    outline thickness.
+- Writes require Resolve **fully quit** (checked through the process list,
+  plus `iConfirmProjectClosed:true`), take a unique SQLite snapshot backup
+  including committed WAL pages, refuse unsupported schemas, and run the edit
+  and its readback in one transaction. `verified:true` means database
+  readback, not a render. SQLite uses `better-sqlite3`, or `node:sqlite` on
+  Node 22.16+ / 23.8+. See `docs/guides/subtitle-track-editing.md`.
+- A live `TimelineItem.SetProperty` on a subtitle item is refused before the
+  automatic timeline archive, with a pointer to these actions.
+
+Contributed by @sidevconcept (#273).
+
+### Changed during review
+
+- **No writes while Resolve runs.** An opt-in to write a project that is not
+  currently loaded was removed. Measured on Studio 19.1.3.7: a project loaded
+  earlier in the session is served from memory when loaded again, so a disk
+  write to it is not shown, and saving after editing the same rows
+  overwrites it. A fresh launch does read it.
+- **Text colour.** The writer set the Word Highlight macro's `Clone` colour
+  controls, which do not render, leaving the template's default pale yellow;
+  it now writes the Text+ shading inputs (`Red1`/`Green1`/`Blue1`/`Alpha1`).
+- **Handle release.** A guarded database is closed when a schema query throws,
+  a likely cause of the slow tests reported on Windows.
+
+### Validation
+
+- Contributor-validated on Studio 21.1.0.17 / Windows: a synthetic caption
+  edit, full quit, database write, relaunch and burn-in render passed on all
+  630 decoded frames, with white base text, yellow highlighting and exact
+  word transitions, checked against a natively configured control. Not
+  rendered on this project's 19.1.3.7 host.
+- Offline: Node advanced suite 1,036 tests / 0 failed in a clean worktree;
+  Python suite green.
+
 ## What's New in v4.9.3 — .drp bin registry for two or more bins; broader temp-root guard tests
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.9.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.10.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(389%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.9.3-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.10.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(389%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.9.3 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.10.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/SKILL.md

@@ -418,6 +418,14 @@ Operating rules an agent must know:
   `iConfirmProjectClosed:true`; every write auto-backs-up and read-back
   verifies. Resolve caches open projects in memory: after patching, fully QUIT
   and relaunch Resolve or the patch will not be visible.
+- **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
+  animated Fusion holders separately from basic `list_subtitle_styles`.
+  New subtitle writes enforce full Resolve quit BEFORE patching, snapshot the
+  SQLite DB and verify transactionally. See
+  [subtitle-track editing](guides/subtitle-track-editing.md) for selectors,
+  Word Highlight controls, dry-run examples and live-validation limits.
 - **Guards are load-bearing.** Advanced tools refuse rather than fabricate
   (silent-lie guards): a thrown "refused" error usually means wrong input space,
   log-encoded frames, or missing media — read the message before retrying.

package/docs/guides/subtitle-track-editing.md

@@ -0,0 +1,227 @@
+# Subtitle tracks: captions and animated presets
+
+The advanced server's `project_db` tool edits saved local SQLite projects.
+The live server can generate subtitles with `timeline_ai.create_subtitles`,
+enumerate their items, read names/bounds and delete items. It cannot edit caption
+text, word timings or animation controls through `TimelineItem.SetProperty`.
+Such subtitle property writes are now refused before auto-archiving.
+
+There are two independent kinds of subtitle styling:
+
+- `list_subtitle_styles` / `set_subtitle_style` read/edit the basic track
+  `EffectFiltersBA` font and position. `styled:false` does **not** mean the
+  track has no animation preset.
+- `list_subtitle_presets` / `copy_subtitle_preset` operate on the linked Fusion
+  holder and composition. `set_subtitle_preset` edits named Word Highlight
+  controls inside its nested compressed tool section.
+
+## Required workflow
+
+1. Generate captions in Resolve and save the project. Inspect it with
+   `list_captions`, `list_subtitle_presets` and `check_captions`.
+2. Preview edits with `dryRun:true`. This reads the saved database; unsaved
+   Resolve changes are not visible. Preview IDs for proposed new captions are
+   provisional.
+3. Save and **fully quit Resolve before writing**. New subtitle write actions
+   require `iConfirmProjectClosed:true` and independently inspect running
+   processes. Closing only the project is insufficient. Failure to inspect
+   processes also refuses the write. Loading a *different* project is not
+   enough either: measured on Studio 19.1.3.7, a project loaded earlier in the
+   session is served from memory when it is loaded again, so a disk write to
+   it is not shown, and saving after editing the same rows overwrites it.
+4. Apply the edits, then relaunch Resolve and inspect/render the result.
+
+Each new subtitle write creates a unique `Project.db.subtitle-<time>-<uuid>.bak`
+SQLite snapshot, including committed WAL pages. Edits and readback verification
+run in one transaction: a failure rolls everything back. Preserve the returned
+backup. To recover, quit Resolve and restore that snapshot using your normal
+project-library recovery procedure; do not replace a live database.
+
+`verified:true` means **database readback**, not that Resolve rendered the
+change. Writes never touch source media. Shared/unsupported item dependencies,
+ambiguous timelines, missing tracks and mismatched schemas are refused.
+
+## Selectors and discovery
+
+Use `projectName` or an explicit `projectDb` path. Discovery searches the
+standard Windows `%APPDATA%/Blackmagic Design/DaVinci Resolve/Support`, macOS
+Application Support (including the App Store sandbox), and Linux
+`~/.local/share/DaVinciResolve` libraries. Both `Resolve Project Library` and
+`Resolve Disk Database` layouts are considered. Relocated libraries need an
+explicit path; these subtitle actions do not operate on Postgres libraries.
+
+`timeline` is the saved timeline name; `track` is the 1-based subtitle-track
+index (default 1). Vector associations determine track order. Duplicate timeline
+names require disambiguation in Resolve before editing.
+
+SQLite uses `better-sqlite3` when its native binding loads, otherwise
+[`node:sqlite`](https://nodejs.org/docs/latest-v24.x/api/sqlite.html) on a suitable
+Node runtime (22.16+ or 23.8+, which provide `node:sqlite` `backup()`; tested on
+24.14.1 and 22.22.3). Zstd reads use native
+`node:zlib` when available and otherwise `fzstd`. Caption writes emit the raw
+`0x80` envelope, avoiding a native compression dependency.
+
+## Captions
+
+```json
+{"action":"list_captions","args":{"projectName":"My Project","timeline":"Reel"}}
+```
+
+Results contain `fps`, `timeUnit:"timeline_frames"` and `captions` with
+`id`, `text`, `start`, `end`, `words:[{text,start,end}]`, `originalWords`,
+`anchor` and any `decodeIssues`. Bounds are absolute timeline frames, with
+exclusive ends. Word frames may be fractional because storage uses 60 ticks
+per second. Caption starts/ends must be nonnegative integer frames.
+
+Current words come from protobuf fields 14/15/16; original AI words from
+18/19/20. Field 21 is a frame anchor. The decoder accounts for a caption moved
+after that anchor was written. `Name` is only a fallback: UI text edits can
+leave it stale, and can produce inconsistent word intervals. No assumption is
+made that saving in Resolve will repair those intervals.
+
+```json
+{
+  "action":"write_captions",
+  "args":{
+    "projectName":"My Project", "timeline":"Reel", "dryRun":true,
+    "replace":[{
+      "id":"<caption-id>", "text":"Hello world", "start":108000, "end":108060,
+      "words":[{"text":"Hello","start":108000,"end":108030},
+               {"text":"world","start":108030,"end":108060}]
+    }],
+    "add":[{
+      "text":"Welcome", "start":108090, "end":108120,
+      "words":[{"text":"Welcome","start":108090,"end":108120}]
+    }],
+    "delete":["<another-caption-id>"]
+  }
+}
+```
+
+For a write, replace `dryRun:true` with `iConfirmProjectClosed:true` after
+quitting Resolve. `replace` supplies complete caption content/timing, not a
+partial patch. Text must equal trimmed words joined with spaces. New captions
+clone a caption already on that track (optionally `templateCaptionId`) to
+preserve the unknown schema fields; adding to a completely empty track is
+currently refused. Replacements preserve original AI words and unknown fields;
+additions clear inherited AI history and markers. `Items` associations are
+re-indexed by time without modifying `FusionCompHolderItems`.
+
+Invalid word intervals, gaps, overlaps, conflicting IDs, or captions that
+overlap are rejected. Boundaries are quantised to 60 Hz before verification;
+a word that becomes zero length after rounding is also rejected. Existing
+untouched captions are reported by QC rather than silently retimed.
+
+`check_captions` takes the same selectors and optional `maxCharacters` (24 by
+default). It reports gaps, invalid/missing timings, overlaps, out-of-bounds
+words, decode count mismatches and long lines. The character limit is a
+heuristic for vertical captions, **not** a pixel-width calculation: font,
+size and position determine actual clipping. It never rewrites timing.
+
+## Animated preset copying and controls
+
+```json
+{
+  "action":"copy_subtitle_preset",
+  "args":{
+    "sourceProject":"Reference", "sourceTimeline":"Reel", "sourceTrack":1,
+    "projectName":"My Project", "timeline":"Reel", "track":1,
+    "replace":false, "dryRun":true,
+    "inputs":{
+      "font":"Open Sans", "fontStyle":"Semibold", "size":0.08,
+      "position":[0.5,0.3],
+      "textRed":1, "textGreen":1, "textBlue":1, "textAlpha":1,
+      "highlightRed":1, "highlightGreen":0.8, "highlightBlue":0,
+      "outlineEnabled":1, "outlineRed":0, "outlineGreen":0, "outlineBlue":0,
+      "thickness":0.03
+    }
+  }
+}
+```
+
+`sourceProjectDb` can replace `sourceProject`. For compatibility with the
+workflow brief, `source_project`, `source_timeline`, `target_project` and
+`target_timeline` alias those project/timeline selectors; `project` aliases
+`projectName`. Do not pass an alias and its canonical selector together.
+
+Copying clones the holder, its track association and its composition with new
+UUIDs. An occupied destination requires `replace:true`; the source is unchanged.
+Omit `inputs` to copy the preset bytes unchanged. To adjust an existing preset,
+use `set_subtitle_preset` with target selectors and `inputs`.
+
+Colour channels are 0–1, `outlineEnabled` is 0 or 1, `size` is Fusion's
+normalised text size (not points), `position` is Fusion Center `[x,y]`, and
+`thickness` is the template's HOutlineThickness value. Parameter editing is
+restricted to the inspected Word Highlight template and literal Template
+TextPlus inputs. Connected/animated inputs and unsupported layouts are refused.
+Missing input values in the listing mean Resolve/template defaults, not zero.
+Other supported composition envelopes can be cloned unchanged, but cannot have
+their parameter meanings guessed. Preset holder Duration is preserved from the
+reference (observed 150); it is not extended to caption-track length.
+
+## Evidence and outstanding live acceptance
+
+On 2026-10-02 a read-only probe on Studio 21.1.0.17/Windows confirmed the API
+boundary on an 11-caption timeline. Saved local project inspection confirmed
+the caption encoding and Word Highlight's nested zlib inputs. Synthetic tests
+exercise both codecs, cloning, transactional rollback, frame-rate arithmetic,
+guard refusal, backup readback and preservation of unrelated tracks.
+
+On 2026-10-06, a synthetic-only caption edit → full quit → database write →
+relaunch → BurnIn render acceptance passed on Studio 21.1.0.17 / Windows.
+Seven generated captions were edited through the actual `project_db` handler:
+six replacements, one deletion and one addition, with explicit word boundaries.
+A fresh native Word Highlight preset was created in the disposable project;
+no personal project or media was used as a preset reference.
+
+The 21-second 1080x1920 / 30 fps render contained 630 frames. All 420 caption
+frames contained text, all seven word transitions matched the written timings,
+and no caption pixels touched the frame edges or appeared in the gaps. The
+rendered text was visually inspected for all seven captions in both highlight
+states. Resolve's live text/bounds and saved word timing readback also matched.
+The original frame check did not assert base text colour. The maintainer's
+[acceptance review](https://github.com/samuelgursky/davinci-resolve-mcp/pull/273#issuecomment-6048433383)
+found that the non-highlighted word remained pale yellow. The codec now targets
+TextPlus shading inputs (`Red1`, `Green1`, `Blue1`, `Alpha1`) rather than the
+macro's `Clone` controls. On 2026-10-08, the original track's Inspector confirmed
+`#ffeb85` text. A fresh native Word Highlight, configured through Resolve's UI
+with `#ffffff` text and `#ffff00` highlight, rendered white. After a full quit,
+the corrected MCP write and relaunch also rendered white with Segoe UI Black,
+centred position and black outline at thickness 0.1.
+
+Both new 1080x1920 renders passed checks on all 630 decoded frames: all 420
+caption frames had white base text and yellow highlighting, with exact word
+transitions and no text in the gaps or at the frame edges. Bright fill pixels
+were measured independently per word, and the original render failed the new
+white-text assertion on all 420 caption frames. All seven captions were also
+visually reviewed in both highlight states; the pixel check is not OCR. Selected
+frame PNGs retain the full render resolution. Generated frames and reports are
+kept outside the repository. The earlier green-pixel live harness was removed
+because its pass flag did not establish word timing or text colour.
+
+The earlier failed synthetic render prompted a codec regression fix: inserting
+absent controls after a final input without a trailing comma produced invalid
+Lua. The writer now prepends comma-terminated inputs, and a regression fixture
+covers the missing separator. The new acceptance run exercises this path.
+
+That live run also exposed Resolve's association constraints: DbIndex must be
+nonnegative and its composite primary key uses ON CONFLICT REPLACE. The writer
+now rebuilds only the selected track's Items vector within the transaction,
+avoiding both rejected temporary indices and lost neighbours during reordering.
+The regression fixture includes those constraints.
+
+To repeat acceptance, use a disposable project and synthetic speech/media:
+generate subtitles, apply Word Highlight with explicit colours, correct two
+captions, add one and delete one, reopen Resolve, then render with
+`ExportSubtitle:true, SubtitleFormat:"BurnIn"`. Inspect rendered frames across
+every word boundary and at the frame edges. Readback alone cannot establish
+visible highlighting, absence of blank frames, or safe margins. Assert the
+non-highlighted text colour separately from the highlighted word, check every
+decoded frame against the written word intervals, and check the caption gaps.
+Review the rendered words visually too: pixel colour checks are not OCR.
+
+Also still unverified: holder Duration semantics, per-caption preset rows,
+whether/when UI edits are retimed on save, and SRT import preserving word
+timings on 21.1. A previously reported ImportMedia(SRT)+AppendToTimeline route
+on 21.0.4.5 is not evidence that SRT carries word timings on another build.
+Repeat the probe and render test after Resolve updates.

package/docs/kernels/audio-fairlight-kernel.md

@@ -1,5 +1,10 @@
 # Audio / Fairlight Kernel
 
+For caption text, per-word timing, additions/deletions and animated subtitle
+presets, use advanced `project_db` after saving and fully quitting Resolve.
+See [subtitle-track editing](../guides/subtitle-track-editing.md). The basic
+`set_subtitle_style` action does not edit animated Fusion presets.
+
 The Audio / Fairlight kernel expands `timeline` into a safer audio-state,
 mapping, voice isolation, auto-sync, transcription, subtitle, and Fairlight
 boundary layer.

package/docs/reference/api-limitations.md

@@ -167,22 +167,22 @@ equivalent, blocking full automation.
 ### Per-subtitle text content and timing editing
 
 - **Object:** `TimelineItem (subtitle track)`
-- **Behavior:** TimelineItem on a subtitle track exposes only 21 standard transform/composite properties (Pan, Tilt, ZoomX, Opacity, Crop, etc.). There are no methods to get or set subtitle text (GetText/SetText), start time, end time, or duration for individual subtitle items. Subtitles created via CreateSubtitlesFromAudio or imported via the Resolve UI cannot have their content or timing read or modified programmatically. Verified via dir() and GetProperty() on Resolve 21.0.0.48.
-- **Workaround / current handling:** No workaround exists — subtitle text and timing are completely inaccessible from the scripting API. Must be edited in the Resolve UI.
+- **Behavior:** GetName, GetStart and GetEnd read caption names and bounds, and Timeline.DeleteClips can delete captions. There are no public methods to set caption text or per-word timings. Read-only live probe on Studio 21.1.0.17 (Windows, 2026-10-02): GetType=generator, GetProperty returned an empty dict, GetFusionCompCount=0, and dir() exposed no caption/text methods; the supplied reproduction also reports false GetProperty/SetProperty results. A subtitle SetProperty request must be refused before timeline auto-archiving. In the supplied 21.1 reproduction, UI text edits leave Name stale and move original AI words/times to protobuf f18/19/20; current f14/15/16 may contain invalid intervals. Whether a later save re-times them is not established here.
+- **Workaround / current handling:** Use advanced project_db list_captions / write_captions / check_captions on a local SQLite project with Resolve fully quit. Current text comes from f14, not stale Name. f15/16 and f19/20 use 60 ticks/sec; f21 is the original caption frame anchor. The tool returns timeline-frame times rebased to the item's current Start. Writes need explicit word times, preserve unknown fields, reject gaps/zero durations and re-index Items atomically, with backup and readback. This is an unsupported DB workaround; render/reopen validation of the implementation remains required before release.
 - **Tags:** missing-method, subtitle, text, timing
 
 ### Subtitle track styling and presets
 
 - **Object:** `TimelineItem / Timeline / Project`
-- **Behavior:** There is no API method to set or query subtitle font family, font size, text color, background color, outline, shadow, position, alignment, or to apply/query subtitle style presets. TimelineItem.GetProperty() on subtitle items returns only transform/composite keys. Timeline.GetSetting() and Project.GetSetting() return None for all probed subtitle-style keys (e.g. 'subtitleFontName', 'subtitleFontSize', 'subtitleTextColor', 'subtitleBackgroundColor', 'subtitlePosition', 'subtitleAlignment', 'subtitlePreset', 'subtitleStyle'). Verified via dir(), GetProperty(), and GetSetting() on Resolve 21.0.0.48.
-- **Workaround / current handling:** No API workaround exists, but the style IS reachable below the API: it lives in Sm2TiTrack.FieldsBlob for Type=2 tracks, as an EffectFiltersBA payload whose effect 136 carries a Qt QFont descriptor (param 18) and a normalised position vector (param 17). Exposed as project_db list_subtitle_styles / set_subtitle_style (font family/size/weight/italic + position). Confirmed live on BOTH editions 2026-08-06 — Studio 19.1.3 and free 21.0.3, identical behaviour: Resolve opens a patched track and re-serialises it back to its own zstd form with the patched values intact, so it genuinely parses the write. Caveats: whole-TRACK style not per-caption, project must be CLOSED, Resolve must be fully quit and relaunched afterwards, and the track must already carry a style blob (a freshly added subtitle track has none until it is styled once in the UI). Burn-in overlays via Fusion titles remain a visual alternative but do not produce subtitle tracks.
+- **Behavior:** There is no API method to set or query subtitle font family, font size, text color, background color, outline, shadow, position, alignment, or to apply/query subtitle style presets. Older probes returned only transform/composite keys; a read-only Studio 21.1.0.17 probe returned an empty dict. Timeline.GetSetting() and Project.GetSetting() return None for all probed subtitle-style keys (e.g. 'subtitleFontName', 'subtitleFontSize', 'subtitleTextColor', 'subtitleBackgroundColor', 'subtitlePosition', 'subtitleAlignment', 'subtitlePreset', 'subtitleStyle'). Verified via dir(), GetProperty(), and GetSetting() on Resolve 21.0.0.48.
+- **Workaround / current handling:** No API workaround exists, but the style IS reachable below the API: it lives in Sm2TiTrack.FieldsBlob for Type=2 tracks, as an EffectFiltersBA payload whose effect 136 carries a Qt QFont descriptor (param 18) and a normalised position vector (param 17). Exposed as project_db list_subtitle_styles / set_subtitle_style (font family/size/weight/italic + position). Confirmed live on BOTH editions 2026-08-06 — Studio 19.1.3 and free 21.0.3, identical behaviour: Resolve opens a patched track and re-serialises it back to its own zstd form with the patched values intact, so it genuinely parses the write. Caveats: whole-TRACK style not per-caption, project must be CLOSED, Resolve must be fully quit and relaunched afterwards, and the track must already carry a style blob (a freshly added subtitle track has none until it is styled once in the UI). Burn-in overlays via Fusion titles remain a visual alternative but do not produce subtitle tracks. Animated Word Highlight is DIFFERENT: list_subtitle_styles may report styled:false while an animation is present. Sm2TiItem_Sm2TiTrack links a Sm2TiVideoClip holder via FusionCompHolderItems to a Sm2TiCompositionTable. The supplied Studio 21.1.0.17 reproduction verified cloning these three rows; local read-only inspection corroborated the format. Use list_subtitle_presets / copy_subtitle_preset, or set_subtitle_preset for named Word Highlight inputs inside the nested zlib tool section. These new actions check that Resolve is fully quit BEFORE writing. Holder Duration is preserved; its rendering semantics and per-caption preset layouts remain unverified.
 - **Tags:** missing-method, subtitle, style, preset
 
 ### Speech recognition engine selection and SRT import
 
 - **Object:** `Timeline`
-- **Behavior:** Timeline.CreateSubtitlesFromAudio(autoCaptionSettings) always uses the built-in Resolve speech recognition engine. There is no API parameter to select an alternative provider (e.g. whisper-cli, Google Speech, AWS Transcribe). The language selection via resolve.AUTO_CAPTION_LANGUAGE_* is the only customization; the engine itself cannot be changed. Furthermore, there is no API method to import an SRT file into a subtitle track programmatically — File -> Import -> Subtitle is UI-only.
-- **Workaround / current handling:** No workaround exists for provider selection or SRT import. External transcripts must be converted to SRT and imported through the Resolve UI.
+- **Behavior:** Timeline.CreateSubtitlesFromAudio(autoCaptionSettings) always uses the built-in Resolve speech recognition engine. There is no API parameter to select an alternative provider (e.g. whisper-cli, Google Speech, AWS Transcribe). The language selection via resolve.AUTO_CAPTION_LANGUAGE_* is the only customization; the engine itself cannot be changed. There is no dedicated subtitle import method. However, MediaPool.ImportMedia(srt) + AppendToTimeline was reported working on Studio 21.0.4.5 (issue #169). Whether that route carries word timing for animated presets on 21.1 has not been verified; SRT contains only cue timing.
+- **Workaround / current handling:** Use Resolve's engine for CreateSubtitlesFromAudio. For external SRT, test ImportMedia + AppendToTimeline on the exact installed build or import through the UI. Use project_db write_captions for explicit word timings with Resolve fully quit; do not assume SRT supplies them.
 - **Tags:** missing-method, subtitle, transcription, speech-recognition, asr
 
 ### Media Pool folder rename

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.9.3"
+VERSION = "4.10.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.9.3",
+  "version": "4.10.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/README.md

@@ -107,6 +107,12 @@ Each dispatches on an `action`. Highlights:
   Includes `list_subtitle_styles` / `set_subtitle_style` — caption font family/size/weight/italic
   and normalised position, which the scripting API cannot touch at all. Whole-track (not
   per-caption); project must be CLOSED and Resolve fully quit + relaunched afterwards.
+  Animated presets use separate `list_subtitle_presets` / `copy_subtitle_preset` /
+  `set_subtitle_preset` actions; caption text and word timing use `list_captions` /
+  `write_captions` / `check_captions`. These SQLite writes enforce full Resolve
+  quit before editing, take unique backups and verify in a transaction.
+  See [subtitle-track editing](../docs/guides/subtitle-track-editing.md) for
+  parameters, Word Highlight controls and the pending live-render acceptance.
 - **`pipeline`** — the DB-as-truth pipeline foundation (see below).
 - **`deliverable`** — deliverable QC / compliance: `deliverable_qc` (ffprobe a render vs its spec →
   pass/fail per field), `loudness_qc` (ebur128 LUFS/true-peak/LRA), `reframe_blanking_check`,

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

@@ -6,12 +6,14 @@
  * verify. The schema map is Resolve 21 / ProjectVersion 17 (the design notes design notes);
  * the column guard refuses rather than corrupting if the schema differs.
  *
- * Needs the optional native dep `better-sqlite3` (lazy).
+ * Uses optional better-sqlite3 or node:sqlite (lazy, compatible adapter).
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import childProcess from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
@@ -41,9 +43,8 @@ export const PROJECT_LIBRARY_ROOT = path.join(os.homedir(), 'Library/Application
  * Project.db found", sending exactly the users the in-app bridge exists to serve
  * hunting for a path they have no reason to know.
  *
- * macOS-only: the sandbox container is an Apple construct. Where the free
- * edition keeps its library on Windows and Linux is NOT verified here, so
- * nothing is guessed for those platforms — pass `projectDb` explicitly there.
+ * macOS-only: the sandbox container is an Apple construct. Windows/Linux
+ * use the platform roots returned by projectLibraryRoots below.
  */
 export const LITE_DB_ROOT = path.join(
   os.homedir(),
@@ -51,7 +52,16 @@ export const LITE_DB_ROOT = path.join(
 );
 
 /** Every root searched when resolving a project by name, Studio first. */
-export const DB_ROOTS = [DISK_DB_ROOT, PROJECT_LIBRARY_ROOT, LITE_DB_ROOT];
+export function projectLibraryRoots(platform = process.platform, home = os.homedir(), env = process.env) {
+  const join = platform === 'win32' ? path.win32.join : path.posix.join;
+  const libraries = (base) => ['Resolve Project Library', 'Resolve Disk Database']
+    .map((name) => join(base, name, 'Resolve Projects'));
+  if (platform === 'win32') return libraries(join(env.APPDATA || join(home, 'AppData', 'Roaming'),
+    'Blackmagic Design', 'DaVinci Resolve', 'Support'));
+  if (platform === 'linux') return libraries(join(home, '.local', 'share', 'DaVinciResolve'));
+  return [DISK_DB_ROOT, PROJECT_LIBRARY_ROOT, LITE_DB_ROOT];
+}
+export const DB_ROOTS = projectLibraryRoots();
 
 /**
  * Filter roots to the ones that answer a readdir within `deadlineMs`.
@@ -92,7 +102,75 @@ export async function responsiveRoots(roots = DB_ROOTS, deadlineMs = 3000) {
 }
 
 export function loadSqlite() {
-  return requireBetterSqlite3('Project.db patching');
+  // A successful require alone doesn't detect a native ABI mismatch: the
+  // bindings are loaded by the constructor. Probe before selecting a backend.
+  try {
+    const Database = requireBetterSqlite3('Project.db patching');
+    const probe = new Database(':memory:');
+    probe.close();
+    return Database;
+  } catch (nativeError) {
+    // DatabaseSync shipped in 22.13, but snapshotBackup needs sqlite.backup(),
+    // added in 22.16 (23.8 on the 23 line). Without it a write would fail only
+    // after opening the database, with "backup is not a function".
+    let builtin;
+    try { builtin = require('node:sqlite'); } catch { builtin = null; }
+    if (typeof builtin?.backup !== 'function') {
+      throw new Error(`${nativeError.message} Alternatively use Node 22.16+ (or 23.8+), whose node:sqlite provides backup().`);
+    }
+    return BuiltinSqlite;
+  }
+}
+
+// Small better-sqlite3-compatible surface used by Project.db consumers. Keep
+// rows as ordinary objects and blobs as Buffers on either backend.
+export class BuiltinSqlite {
+  constructor(filename, { readonly = false } = {}) {
+    const { DatabaseSync } = require('node:sqlite');
+    this.db = new DatabaseSync(filename, { readOnly: readonly, enableForeignKeyConstraints: false });
+  }
+  exec(sql) { this.db.exec(sql); return this; }
+  close() { this.db.close(); }
+  prepare(sql) {
+    const stmt = this.db.prepare(sql);
+    const row = (r) => r && Object.fromEntries(Object.entries(r)
+      .map(([k, v]) => [k, v instanceof Uint8Array ? Buffer.from(v) : v]));
+    return { get: (...args) => row(stmt.get(...args)),
+      all: (...args) => stmt.all(...args).map(row), run: (...args) => stmt.run(...args) };
+  }
+  transaction(fn) {
+    return (...args) => {
+      this.exec('BEGIN IMMEDIATE');
+      try { const result = fn(...args); this.exec('COMMIT'); return result; }
+      catch (error) { this.exec('ROLLBACK'); throw error; }
+    };
+  }
+  backup(filename) { return require('node:sqlite').backup(this.db, filename); }
+}
+
+/** Verify the process is gone; a caller assertion alone is not sufficient. */
+export function requireResolveQuit(opts) {
+  requireClosed(opts);
+  if (resolveRunning()) throw new Error('Fully QUIT Resolve before subtitle database writes (Resolve is running).');
+}
+
+function resolveRunning() {
+  const win = process.platform === 'win32';
+  const result = childProcess.spawnSync(win ? 'tasklist.exe' : 'ps',
+    win ? ['/FO', 'CSV', '/NH'] : ['-A', '-o', 'comm='],
+    { encoding: 'utf8', timeout: 5000, windowsHide: true });
+  if (result.error || result.status !== 0) throw new Error('Cannot verify Resolve is quit; refusing database write.');
+  return result.stdout.split(/\r?\n/).some((line) => win
+    ? /^"Resolve\.exe",/i.test(line.trim())
+    : /(^|\/)resolve(?:\.exe)?$/i.test(line.trim()));
+}
+
+/** SQLite snapshot includes committed WAL pages; never overwrite an older backup. */
+export async function snapshotBackup(dbPath) {
+  const filename = `${dbPath}.subtitle-${Date.now()}-${randomUUID()}.bak`;
+  const db = openGuarded(dbPath);
+  try { await db.backup(filename); } finally { db.close(); }
+  return filename;
 }
 
 /**
@@ -137,7 +215,7 @@ export function resolveDbPath({ projectDb, projectName, roots, skippedRoots = []
           'are invisible until macOS unwedges it. '
         : '') +
       'If Resolve keeps its projects elsewhere — a relocated library, a network/Postgres ' +
-      'database, or the free edition on Windows/Linux — pass projectDb with the full path.',
+      'database — pass projectDb with the full local SQLite path (Postgres is not a Project.db file).',
     );
   }
   if (hits.length > 1) {
@@ -153,19 +231,22 @@ export function openGuarded(dbPath, { writable = false, table, column } = {}) {
   const Database = loadSqlite();
   if (!fs.existsSync(dbPath)) throw new Error(`Project.db not found: ${dbPath}`);
   const db = new Database(dbPath, { readonly: !writable });
-  if (table && column) {
-    // Quote the table identifier — Resolve tables like "ListMgt::LmVersion" contain "::" which is an
-    // illegal token unquoted (the PRAGMA would fail with "unrecognized token: :").
-    const cols = db
-      .prepare(`PRAGMA table_info("${String(table).replace(/"/g, '""')}")`)
-      .all()
-      .map((c) => c.name);
-    if (!cols.includes(column)) {
-      db.close();
-      throw new Error(`${table}.${column} not found — unsupported Project.db schema/version; refusing to patch.`);
+  try {
+    if (table && column) {
+      // Quote identifiers: Resolve table names can contain "::".
+      const cols = db
+        .prepare(`PRAGMA table_info("${String(table).replace(/"/g, '""')}")`)
+        .all()
+        .map((c) => c.name);
+      if (!cols.includes(column)) {
+        throw new Error(`${table}.${column} not found — unsupported Project.db schema/version; refusing to patch.`);
+      }
     }
+    return db;
+  } catch (error) {
+    db.close();
+    throw error;
   }
-  return db;
 }
 
 export function backup(dbPath) {