davinci-resolve-mcp 4.11.0 → 4.12.0

package/CHANGELOG.md

@@ -2,6 +2,92 @@
 
 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.12.0 — Live subtitle presets and title text across Fusion title tools
+
+Contributed by @sidevconcept (#281). The live behaviour below rests on their
+synthetic runs on **Resolve Studio 21.1.0.17 / Windows**; this release was not
+re-measured live here (the maintainer's machine runs 19.1.3.7).
+
+### New
+
+- **`timeline_ai(action="list_title_presets")`** inventories the installed
+  factory Fusion titles and subtitle presets: local archive, category and full
+  template ID. `templates_archive` points it at a custom installation. It is an
+  inventory, not a claim that each preset works live.
+- **`timeline_ai(action="set_subtitle_preset")`** applies an installed subtitle
+  preset and common literal style inputs (font, size, position and so on) to a
+  subtitle track while Resolve stays open. It writes a **new timeline
+  revision** and keeps the original, compares the edit inventory, and re-exports
+  through Resolve to confirm the preset and controls were kept. It restores the
+  original timeline on failure.
+  - `dry_run` / `dryRun` are coerced at the dispatcher, so `"true"` previews
+    and never imports. A preview that would need a live capture is refused.
+  - The result lists `verified_components` (track counts, item names and
+    bounds, media IDs, preset controls) and `unverified_components` (markers,
+    grades, other Fusion comps, audio). Native readback is not render
+    verification, and the revision is not certified as a full copy.
+  - Staging exports are removed on success and kept for diagnosis on failure
+    (`staging_retained`, `staging_directory`).
+- **`timeline.set_title_text` / `get_title_text` reach more than TextPlus.** The
+  Fusion-comp fallback now finds literal text on TextPlus, sText, Text3D and
+  MultiText (`TextN.StyledText` in native `TextOrder`). It follows
+  `StyledTextFollower` and `PublishText` without disconnecting animation, and it
+  skips connected, expression-driven, locked and disabled inputs rather than
+  flattening them. MultiText editing was validated only on Studio 21.1.0.17 /
+  Windows.
+- **`scripts/edit_subtitle_timeline.mjs`** (backed by
+  `resolve-advanced/server/subtitle-timeline.mjs`) inspects an exported
+  subtitle track, or writes a new file with a bundled preset reference
+  (`Word Highlight`, `Lollipop`) or a native subtitle-template reference applied.
+- Synthetic title-library validation scripts write private QA reports with
+  relative image links; `src/utils/qa_privacy.py` replaces host paths and
+  project/timeline names in saved records.
+
+### Docs
+
+- New guides: `docs/guides/title-library-automation.md` and
+  `docs/guides/subtitle-track-editing.md`.
+
+### Verification
+
+- Contributor (Studio 21.1.0.17 / Windows, synthetic media): all 134 installed
+  factory Fusion presets passed native application, literal text/property
+  readback and sampled rendered-frame checks; all 23 subtitle presets applied
+  without a restart.
+- Here: Python offline suite and Node advanced suite (fresh `npm ci`) green;
+  API parity, api-limitations, read/write symmetry, agent-rule drift and
+  `npm pack` clean.
+
+## What's New in v4.11.1 — `.cube` input ranges, `"false"` import flags and the caption character cap
+
+Three fixes from @Dev-next-gen (#286, #287, #288), each with a reproduction and a
+regression test.
+
+### Fixes
+
+- **A 3D `.cube` carrying `LUT_3D_INPUT_RANGE` could not be read** (#288).
+  `read_cube` knew `DOMAIN_MIN`/`DOMAIN_MAX` but not Resolve's own header form,
+  so the line fell through to the data-row branch and the whole file was refused
+  as a "non-numeric entry". `read_lut_summary` and `attenuate_lut_file` both
+  failed on it. The keyword is now read as one domain for all three channels;
+  attenuation still refuses a non-unit range, exactly as it does for
+  `DOMAIN_MIN`/`DOMAIN_MAX`.
+  - **On landing:** a short or non-numeric `LUT_3D_INPUT_RANGE` escaped as a bare
+    `ValueError`, and a short `DOMAIN_MIN`/`DOMAIN_MAX` produced a silently short
+    domain list. All three headers now go through one reader that raises
+    `CubeLutError` naming the file, line and keyword.
+- **`timeline(action="import_timeline_checked")` read `"false"` as true** (#287).
+  `sanitize_media` / `relink_media` and `import_source_clips` were read with bare
+  `bool()`, so `sanitize_media="false"` still handed Resolve the sanitized copy
+  instead of the file passed, and `import_source_clips="false"` reached
+  `ImportTimelineFromFile` as `importSourceClips: True`. Both now go through
+  `_coerce_bool`, as the rest of `server.py` has since v4.8.20.
+- **Caption orphan rebalancing could break `max_chars_per_line`** (#286).
+  Moving the last word of the penultimate line onto a one-word final line never
+  re-checked the cap, so "we had a wonderful conversation" at 20 characters came
+  out with a 22-character second line in the SRT/WebVTT. The move now happens
+  only when the merged line fits; a lone last word is the lesser fault.
+
 ## What's New in v4.11.0 — `rename_plan` collides names a case-insensitive volume treats as one
 
 ### Fixes

package/README.md

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

package/docs/SKILL.md

@@ -418,7 +418,22 @@ 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` /
+- **Live subtitle effects**: use `timeline_ai.set_subtitle_preset` with Resolve
+  open. `timeline_ai.list_title_presets` discovers installed title/subtitle names
+  and full IDs. `preset` accepts a bundled or installed subtitle preset; omit it
+  to adjust the existing effect. `inputs` accepts common literal font/style,
+  size/position and text RGBA; highlight/outline controls are Word Highlight-specific.
+  Native DRT export/edit/import creates and selects a recoverable revision,
+  preserving the original. Do not ask the user to quit or relaunch for effects.
+  Render frames to verify appearance; inventory/readback alone is insufficient.
+  Installed presets are captured through the native title API in a temporary
+  timeline, then applied to the subtitle track. Common controls also work for
+  Lollipop. Never guess unmapped effect controls. `preset_reference` accepts a
+  native subtitle DRT; unbundled dry runs require such a reference.
+  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.
+- **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
   animated Fusion holders separately from basic `list_subtitle_styles`.

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

@@ -1,5 +1,88 @@
 # Subtitle tracks: captions and animated presets
 
+## Live effects: keep Resolve open
+
+For routine video changes, use the live server's
+`timeline_ai(action="set_subtitle_preset", params={...})`. Do not route subtitle
+effect changes to `project_db` or ask the user to quit/relaunch Resolve.
+
+```json
+{
+  "action":"set_subtitle_preset",
+  "params":{
+    "track":1, "preset":"Word Highlight",
+    "inputs":{
+      "font":"Segoe UI", "fontStyle":"Black", "size":0.065,
+      "position":[0.5,0.4], "textRed":1, "textGreen":1, "textBlue":1,
+      "highlightRed":1, "highlightGreen":1, "highlightBlue":0,
+      "outlineEnabled":1, "outlineRed":0, "outlineGreen":0,
+      "outlineBlue":0, "thickness":0.1
+    }
+  }
+}
+```
+
+This exports the current native DRT, edits only its subtitle Fusion holder,
+then imports and selects a new timeline revision. The original timeline remains
+recoverable. Successful operations, including dry runs, delete their staging
+exports. Failures keep the staging folder for diagnosis and return
+`staging_retained:true` and `staging_directory`; remove that folder when diagnosis
+is complete because it contains full timeline exports. Cleanup failures also
+report the retained folder with a warning. It never edits the open database, changes source
+media or requires an application restart. `dry_run:true` prepares the exported
+revision without importing it. Omit `preset` to incrementally adjust the
+current Word Highlight instead of replacing it. `preset_reference` can name
+another native DRT, with `reference_track` selecting its subtitle track.
+`revision_name` is optional and must be unique in the current project.
+
+`preset:"Word Highlight"` applies a bundled native holder exported from the
+synthetic Studio 21.1.0.17 acceptance project. Its reference settings are Segoe
+UI Black, size 0.055, centred position, white text, yellow highlight, black
+outline and thickness 0.1; these are reference settings, not claims about UI
+defaults. Explicit `inputs` override them. No reference footage is bundled.
+`preset:"Lollipop"` applies the bundled native Lollipop. Other installed subtitle
+presets are discovered from the local `Templates.drfx`, captured by the running
+Resolve as a native title in an isolated temporary timeline, then applied to the
+subtitle track through native interchange. The temporary capture is removed
+after restoring the original timeline; the original edit remains recoverable.
+No additional vendor template files are redistributed. Use
+`timeline_ai(action="list_title_presets")` to discover names, full template IDs
+and categories. Supply `templates_archive` for a nonstandard installation.
+Full IDs disambiguate names such as the ordinary and animated `Statement`.
+
+All subtitle templates with the inspected `Template = TextPlus` layout accept
+the common literal `font`, `fontStyle`, `size`, `position`, `textRed`, `textGreen`,
+`textBlue`, and `textAlpha` controls. Highlight and outline mappings remain
+specific to Word Highlight. Connected/animated controls, different layouts and
+unmapped effect controls are refused. Do not guess their meanings. The live
+matrix is documented in [title library automation](title-library-automation.md).
+An alternate `preset_reference` can copy another decodable native holder.
+For an unbundled installed preset, a mutation-free dry run needs an existing
+`preset_reference`: discovering its native definition otherwise needs a temporary
+live title. `dry_run` never creates that temporary timeline.
+
+For gradient/image text fills (observed in Grey with Shadow), solid RGB inputs
+are dormant. The writer refuses a colour edit that would only change those
+invisible values. Pass `inputs.textFillMode:"solid"` explicitly to replace the
+fill mode, then supply the desired text RGBA. The stored gradient is retained,
+and the original timeline/reference remains recoverable. Font, size and position
+edits can preserve the gradient by omitting text colour inputs. Readback reports
+the effective `textFillMode`; absent Type1 uses the observed TextPlus solid default.
+
+The handler checks live track counts, item names/bounds and Media Pool media IDs
+against the original, then re-exports the imported timeline through Resolve and
+verifies that it retained the preset controls before selecting the revision.
+`verified_components` lists these checks. Markers, grades, other items' Fusion
+compositions and audio content are **not** compared; they are listed in
+`unverified_components`. This is not verification of a complete timeline copy.
+A failed import/check
+restores the previous active timeline and reports the retained failed revision.
+Resolve re-export readback plus edit inventory is not render verification: inspect rendered
+frames at word boundaries and across caption gaps. Native DRT import was tested
+on Studio 21.1.0.17/Windows without quitting Resolve. Changing sequence IDs in
+only the sequence XML loses subtitle tracks; cross-entry references must remain
+intact. Resolve remaps timeline IDs itself on import.
+
 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
@@ -15,7 +98,13 @@ There are two independent kinds of subtitle styling:
   holder and composition. `set_subtitle_preset` edits named Word Highlight
   controls inside its nested compressed tool section.
 
-## Required workflow
+## Offline database workflow (explicit maintenance only)
+
+The following full-quit requirement belongs to direct database writes, not
+live effect automation. Keep the guard: bypassing it can lose edits. Caption
+text/word-timing DB writes still use this offline workflow; for restart-free
+caption corrections use the live Resolve UI. A generic `SetProperty` refusal
+does not establish that all subtitle workflows require a restart.
 
 1. Generate captions in Resolve and save the project. Inspect it with
    `list_captions`, `list_subtitle_presets` and `check_captions`.
@@ -152,8 +241,9 @@ 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.
+based on common literal Template TextPlus inputs for subtitle templates;
+highlight and outline controls are specific to Word Highlight.
+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
@@ -225,3 +315,28 @@ 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.
+
+## Restart-free acceptance (2026-10-08)
+
+`tests/live_subtitle_preset_validation.py` exercised the actual Python
+`timeline_ai.set_subtitle_preset` dispatcher on Studio 21.1.0.17/Windows in the
+disposable synthetic QA project, without launching, quitting or reopening
+Resolve. It removed the animation holder from an exported synthetic timeline,
+imported that bare-caption timeline, then applied the bundled Word Highlight.
+The live action verified seven captions and the video/audio bounds/media IDs,
+and native re-export retained the requested white text and magenta highlight.
+
+Three full-resolution 1080x1920 Resolve-rendered frames were visually inspected:
+at 108200 the first word was magenta and the second white; at 108220 those
+colours swapped; frame 108180 in the caption gap was black. This proves those
+sampled frames, not every frame or other templates/builds. The harness restores
+the previous timeline, playhead and page. Earlier live runs also demonstrated
+incremental colour, size and position edits, followed by a random-colour change
+requested as a demonstration. Random colours are not the bundled defaults.
+
+A subsequent Lollipop test on the same running Studio session applied the
+effect through the native UI, then through the updated MCP action using the
+bundled reference. Resolve's re-export confirmed
+`Templates/Edit/Titles/Subtitles/Animated/Lollipop`; a rendered frame showed its
+native yellow text and orange outline. No application restart was needed.
+This Windows acceptance does not establish Mac compatibility; repeat it there.

package/docs/guides/title-library-automation.md

@@ -0,0 +1,109 @@
+# Native title and subtitle library automation
+
+Keep Resolve Studio open. Discover the installed factory Fusion presets with
+`timeline_ai(action="list_title_presets", params={})`. The inventory names the
+local archive, category and full template ID; it does not imply live acceptance.
+Use `templates_archive` when automatic discovery cannot find a custom installation.
+Factory inventory does not enumerate third-party packs or the basic non-template
+Text/Scroll generators. Installed fonts and tool availability remain host-specific.
+
+## Ordinary Fusion titles
+
+Insert with `timeline(action="insert_fusion_title", params={"name":
+"Templates/Edit/Titles/Candy"})`, then identify the inserted clip and use
+`fusion_comp.probe_fusion_comp` / `probe_fusion_tool` with `clip_id` or an explicit
+timeline-item selector. Read the actual graph and controls before editing.
+`safe_set_inputs` can set literal inputs on the inspected tool, including text,
+font, size and colour. Many presets use TextPlus; others use sText or Text3D.
+Do not assume every template has a tool called `Template`, flatten connected
+animation controls, or overwrite text instances linked to another tool.
+
+`timeline.set_title_text` also supports literal TextPlus, sText, Text3D and
+MultiText inputs. For a connected StyledTextFollower it edits the modifier's
+literal `Text` input; for PublishText it uses `Value`. MultiText uses the native
+`TextN.StyledText` controls in native `TextOrder`; `TextValueN` changes list
+labels without changing rendered text. Expressions and
+unknown modifier chains are refused rather than flattened. The default text
+action edits the first supported text target; use explicit Fusion tools when
+changing multiple independent title lines. Render to verify the resulting text.
+MultiText editing was validated only on Studio 21.1.0.17 / Windows.
+
+Use the full template ID rather than a leaf name: `Statement` exists both as an
+ordinary title and an animated subtitle. Probe `comp.GetData("TEMPLATE_ID")`
+to confirm which template native insertion selected.
+
+## Subtitle-track presets
+
+```json
+{"action":"set_subtitle_preset","params":{
+  "preset":"Templates/Edit/Titles/Subtitles/Animated/Rotate",
+  "inputs":{"size":0.06,"position":[0.5,0.25],
+            "textRed":0.15,"textGreen":0.85,"textBlue":1}
+}}
+```
+
+The live helper captures the installed template in its own temporary timeline,
+exports its native composition, restores the working timeline and removes only
+that temporary capture. It swaps the exported subtitle holder composition,
+imports a recoverable revision, checks edit/media inventory and re-exports the
+revision to confirm native preset/control retention. The original timeline
+remains intact. The inventory compares track counts, item names/bounds and media
+IDs; it does not compare markers, grades, other Fusion compositions or audio
+content. Results list both verified and unverified components. Inspect the
+revision before relying on it as a complete copy.
+Successful operations, including previews, remove staging exports; failures
+retain them for diagnosis and report `staging_retained` and `staging_directory`.
+Cleanup failures warn and report the retained folder. These files contain full
+timeline exports and should be removed after diagnosis. It never writes an open
+Project.db or changes source files.
+
+Common mapped literal controls are `font`, `fontStyle`, `size`, `position`,
+`textRed`, `textGreen`, `textBlue` and `textAlpha`. Highlight/outline mappings are
+specific to Word Highlight. Unsupported controls/layouts and animated or
+connected input replacements are refused. An imported preset readback is not a
+rendered check. Inspect caption word phases, gaps and safe margins.
+
+Gradient/image fills do not render their dormant solid RGB values. A subtitle
+colour edit refuses that case unless `textFillMode:"solid"` explicitly requests
+replacement of the fill mode. Grey with Shadow uses a native gradient; preserve
+it when editing only font/size/position, or explicitly select solid fill when
+requesting a uniform colour. The gradient data/reference stays recoverable.
+For ordinary Fusion titles, inspect the active shading mode/gradient controls;
+a raw RGB readback alone does not establish the rendered fill colour.
+
+Word Highlight and Lollipop have bundled native references. Other factory
+subtitle presets require the local installation or an explicit native subtitle
+`preset_reference`. Unbundled dry runs require a pre-existing reference so no
+live temporary title is created during preview.
+
+## Repeatable acceptance
+
+The [Windows acceptance record](../notes/title-library-acceptance.md) documents
+134 final passing cases and an interrupted ordinary-title retest that required
+automatic Studio crash recovery. It does not establish universal restart-free
+reliability or Mac compatibility.
+
+`tests/live_title_library_validation.py` requires an already-open disposable
+`MCP_QA_*` project with the synthetic caption fixture. It refuses to launch
+Resolve, renders representative native frames, records property readback and
+pixel differences, persists every case, retains test timelines and restores the
+original timeline/page/playhead. Only synthetic project contents may be used.
+
+```powershell
+venv/Scripts/python.exe tests/live_title_library_validation.py --output-dir logs/title-library-full
+```
+
+The image metrics require Pillow and NumPy; `--image-python` can use an independent
+Python installation with those packages. It runs in isolated mode, avoiding
+Resolve's Python environment. `--only` selects exact names/IDs for a focused
+retest. `scripts/title_library_report.py` builds a local HTML matrix and contact
+sheets from one or more reports; a later retest replaces the same template's case.
+The HTML uses relative links to copied QA renders under its `frames/` folder;
+move the entire output folder to view it on another machine. Saved QA records
+replace host workspace/home paths with anonymous markers; they do not retain
+the local account name or workspace folder identity.
+
+Acceptance distinguishes native application, literal property readback and
+sampled rendered appearance. It does not certify all controls, every animation
+frame, third-party packs, or Mac compatibility. Test Mac separately before
+claiming cross-platform live acceptance.

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

@@ -1,7 +1,9 @@
 # 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.
+For animated subtitle effects use live `timeline_ai.set_subtitle_preset` with
+Resolve open. It applies/adjusts Word Highlight through native DRT interchange
+and selects a recoverable revision. For caption text/word timing use the live
+UI, or explicit offline advanced `project_db` maintenance after fully quitting.
 See [subtitle-track editing](../guides/subtitle-track-editing.md). The basic
 `set_subtitle_style` action does not edit animated Fusion presets.
 

package/docs/kernels/fusion-composition-kernel.md

@@ -1,5 +1,14 @@
 # Fusion Composition Kernel
 
+Subtitle-track animation holders do not enumerate as caption Fusion comps.
+For installed subtitle presets and common font, colour, size and position edits,
+use live `timeline_ai.set_subtitle_preset`; Word Highlight also has mapped
+highlight/outline controls. Discover presets with `timeline_ai.list_title_presets`.
+See [subtitle-track editing](../guides/subtitle-track-editing.md) and
+[title library automation](../guides/title-library-automation.md).
+Keep Resolve open. Generic caption `SetProperty`/`GetFusionCompByIndex` is not
+the route, and direct Project.db patching is reserved for explicit offline work.
+
 The Fusion Composition kernel expands `fusion_comp` into a safer graph
 inspection, tool creation, input write, connection, and boundary-report layer
 for timeline item Fusion comps and active Fusion page comps.

package/docs/notes/subtitle-live-automation-audit.md

@@ -0,0 +1,82 @@
+# Live subtitle automation audit — 2026-10-08
+
+The `feat/subtitle-track-support` branch added useful caption/preset codecs but
+routed effect edits only through Project.db. The subsequent full-quit guard was
+correct for that database route; it did not establish that a running Resolve
+could not apply the same effect through native interchange or its own UI.
+
+## Corrected paths
+
+| Finding | Correction |
+|---|---|
+| Word Highlight edits exposed only as offline DB actions | Live `timeline_ai.set_subtitle_preset` exports native DRT, changes the exported holder, imports/selects a new revision; original retained |
+| Applying an effect required a reference in another user project | Bundle a native holder from synthetic QA with explicit reference settings and no media |
+| Subtitle `SetProperty` refusal sent every request to full-quit DB patching | Error now routes effects to the live action; text/timing to live UI or explicit offline maintenance |
+| Skills and kernels directed animation work to the offline server | Updated audio/Fusion portable skills, kernels, operating reference, advanced README and subtitle guide |
+| Codec readback could report success before Resolve parsed the composition | Re-export the imported timeline and compare its retained controls; also compare live edit inventory |
+
+Direct DB-write safety guards remain intact. Never patch the database of an
+open project, including a project loaded earlier in the same Resolve session.
+Native interchange avoids that cache hazard by asking Resolve itself to import
+the changed content.
+
+## Evidence and limits
+
+Live validation on Studio 21.1.0.17/Windows exercised the public dispatcher,
+applied Word Highlight to a bare subtitle track and verified the imported
+controls through native re-export. Seven caption bounds, video/audio bounds and
+media IDs matched. Rendered frames showed the requested white/magenta word
+phases and a blank caption gap. Incremental colour, size and position edits also
+worked, including the user's random-colour demonstration, without a restart.
+See [subtitle-track editing](../guides/subtitle-track-editing.md) and the
+synthetic-only live acceptance script.
+
+That original acceptance certified Word Highlight and unchanged Lollipop
+application, not universal video automation. The subsequent installed-library
+expansion discovers presets, captures their native definitions without UI drags,
+and maps common literal subtitle font, size, position and text RGBA controls.
+Ordinary title text now includes shape/3D/MultiText and supported text modifiers
+without flattening their animation. See
+[title library automation](../guides/title-library-automation.md) for the test
+harness and its measured limits, and the subsequent
+[134-preset acceptance record](title-library-acceptance.md), including its
+ordinary-title crash/recovery. Unmapped subtitle effect controls and caption
+text/timing changes still need observed live UI automation unless another supported
+route is available. Current granular-only clients do not expose the new compound
+action; use the compound server or the shared Python helper. Installed fonts,
+templates, speech models and Resolve build differences remain capabilities to
+probe, not assumptions.
+
+Remaining full-quit references under extension-authoring, offline DB maintenance
+and crash recovery describe distinct operations. Newly installed Fuses and
+some extension categories genuinely have restart requirements. Routine video
+edits should use already available tools or native imported compositions rather
+than turn extension installation into a repeated step. Do not erase those
+constraints to promise "100% automated".
+
+Code already loaded in an MCP process does not automatically change after a
+Git update. Follow the installer/update instructions for the component being
+updated. Bridge-script installation may require Resolve to restart. This
+feature does not change the general launcher or installer lifecycle.
+
+## Validation record
+
+- 169 Python tests in the relevant subtitle, safety, connection, lifecycle,
+  dashboard and documentation suites: passed, one skipped. A subsequent focused
+  run of 53 tests included the added imported-control-loss regression and passed.
+- 28 Node subtitle codec/DB/native-timeline tests passed. The two new native
+  timeline tests also passed independently after the readback helper was added.
+- Native API parity audit passed (existing undocumented-method advisories only).
+- Generated API-limitations, read/write-symmetry and portable-agent assets checked.
+- NPM dry-run package inspection confirmed the live bridge, codec helper and
+  native reference asset are included.
+- Windows test-fixture corrections are split into a separate change: ps fixtures
+  select their intended platform, macOS path assertions normalize separators,
+  and dashboard temporary SQLite connections close before directory removal.
+
+The automation is reviewed separately from subtitle database editing. Studio
+stayed open during the original subtitle acceptance;
+the later full-library title test has the interruption documented above.
+Existing MCP processes still need to load the
+updated Python code to expose the new action; that is separate from restarting
+Resolve.

package/docs/notes/title-library-acceptance.md

@@ -0,0 +1,76 @@
+# Installed title library acceptance — 2026-10-08/09
+
+Windows Resolve Studio 21.1.0.17, branch `feat/subtitle-track-support`, synthetic
+project. Native definitions came from the locally installed factory
+`Templates.drfx`; they were not redistributed. Source media was unchanged.
+
+## Final measured result
+
+| Factory category | Applied | Property readback and sampled renders |
+|---|---:|---:|
+| Ordinary Fusion titles / lower thirds | 111 | 111 passed |
+| Static subtitle presets | 18 | 18 passed |
+| Animated subtitle presets | 5 | 5 passed |
+| Total | 134 | 134 passed after corrections and retests |
+
+Native title insertion used full IDs and checked `TEMPLATE_ID`. Supported
+independent text targets received `MCP TEST` through the public title-text action
+and scoped Fusion writes. Available literal size/RGB controls were exercised;
+connected/expression controls were preserved. Native Deliver captures compared
+the same frame before/after and sampled early/late frames. Final title contact
+sheets show the requested text. Material/gradient-driven colours are not
+certified by dormant RGB readback.
+
+Subtitle tests used the public live action with size, position and text RGB.
+Imported revisions preserved edit/media inventory and retained preset/controls
+in a native re-export. Two caption word samples rendered visibly, with a blank
+gap sample. Grey with Shadow explicitly selected solid fill for its colour test;
+the native gradient reference stays recoverable. All 23 subtitle presets passed
+without a Resolve application restart.
+
+## Corrections and session failure
+
+- Follow StyledTextFollower base `Text` and PublishText `Value` without flattening
+  the owner's connected StyledText input; support sText and Text3D.
+- MultiText `TextValueN` inputs are passive list labels. Rendered text uses
+  `TextN.StyledText`, ordered by native `TextOrder`. Inspect hidden row input
+  handles before writing. A regression test covers this distinction.
+- Refuse subtitle RGB edits on gradient/image fills unless the caller explicitly
+  requests `textFillMode:"solid"`.
+- Persist harness results before restoration and record restoration failure
+  when scripting disconnects.
+
+The initial complete matrix inserted every preset. A focused retest stalled and
+Studio exited during Two Line Slide while the old MultiText list-label path was
+still loaded in that test process. This records the observed sequence, not a
+proven exclusive crash cause. Process exit was verified. The same Studio
+executable was recovered automatically with no existing Resolve process, and
+the original QA timeline restored. No user reopen was needed. Corrected Letterbox
+Text, Simple Two Lines, Two Line Slide and Zipper then passed a fresh four-case
+native test. The crash prevents claiming an uninterrupted full acceptance run
+or universal 100% restart-free automation.
+
+## Evidence and limits
+
+Local scratch reports: `logs/title-library-full/report.json` (134 initial cases),
+`logs/title-library-retest/report.json` (interrupted focused run and failure
+annotation), `logs/title-library-final-retest/report.json` (four corrected cases
+and restoration readback). `logs/title-library-review/index.html` and
+`matrix.json` merge the latest result per template, preserve session failures and
+link native full-resolution frames. Subtitle contact sheets are labelled detail
+crops; individual cases retain native DRT exports. These artifacts are not
+shipped vendor templates.
+
+Reproduce using [the library guide](../guides/title-library-automation.md),
+`tests/live_title_library_validation.py` on an already-open disposable synthetic
+project, and `scripts/title_library_report.py`. Mac remains untested. Scope
+excludes third-party packs, basic Text/Scroll generators, every effect-specific
+parameter and exhaustive animation frames. Unsupported/connected controls still
+require an observed supported route.
+
+The latest relevant Python run passed 120 tests with one skip; the focused
+title/subtitle run passed 22 tests. Subtitle Node tests passed 31 cases, including
+explicit gradient-fill handling. Generated API limitations, read/write symmetry
+and portable-agent assets/rules passed drift checks. The original synthetic
+timeline and playhead were restored after the final live test.
+Changes remain local; no release or publication was performed.

package/docs/reference/api-limitations.md

@@ -175,7 +175,7 @@ equivalent, blocking full automation.
 
 - **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. 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.
+- **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 database writing. For live Word Highlight effects instead use timeline_ai set_subtitle_preset: native DRT export, patch the exported holder, and native import as a recoverable timeline revision. On Studio 21.1.0.17/Windows (2026-10-08), colour, size and position changed visibly without quitting Resolve; clip/caption bounds and media IDs matched the original. This does not add a native subtitle setter or establish other effects/builds. 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

package/docs/reference/readwrite-symmetry.md

@@ -2,9 +2,9 @@
 
 # Read/Write Symmetry Audit
 
-- write-style action occurrences scanned: **126**
+- write-style action occurrences scanned: **127**
 - write-style action occurrences with a matching read: **76**
-- distinct high-signal `set_` actions without a direct/known readback: **4**
+- distinct high-signal `set_` actions without a direct/known readback: **5**
 
 ## High-signal gaps — `set_` with no direct/known readback
 
@@ -12,6 +12,7 @@
 - `set_high_priority`
 - `set_keyframe_interpolation`
 - `set_node_enabled`
+- `set_subtitle_preset`
 
 ## Low-signal (create/add/insert/apply/import — usually expected): 45 distinct names
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.11.0"
+VERSION = "4.12.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