davinci-resolve-mcp 4.13.6 → 4.14.0

package/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 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.14.0 — Subtitle presets install, and frame capture puts the render page back
+
+Lands #298. Closes #297 and #296. #295 is only the controls the Word Highlight
+macro actually stores.
+
+### Fixed
+
+- **`timeline_ai.set_subtitle_preset` (`src/utils/subtitle_live.py`, `install.py`)**:
+  a fresh installer or control-panel setup never installed `resolve-advanced`'s
+  Node packages, so the first preset call died with `ERR_MODULE_NOT_FOUND`
+  for `jszip`. Setup now runs `npm install --omit=dev --omit=optional` in
+  that directory, and a missing install returns that command instead of the
+  raw Node error.
+- **`timeline_frame` capture (`src/server.py`)**: the single-frame render
+  switched format before it had an output folder, then deleted that folder
+  even when Deliver was still pointed at it. That left the project on JPEG
+  and raised Resolve's "Render Path Inaccessible" dialog. The folder is set
+  first, the previous format and codec are restored as ids (`H264`, not the
+  Deliver label `H.264`), and the temporary folder is removed only after the
+  previous path is back. A project that never had a render path keeps the
+  folder. A timeline with subtitles is told the still does not include them:
+  `ExportSubtitle` cannot be toggled for one frame and then restored.
+
+### Added
+
+- **Word Highlight drop shadow and alignment**: `shadowEnabled`,
+  `shadowRed`/`shadowGreen`/`shadowBlue`, `shadowOffset`, `shadowSoftness`
+  and the X/Y pair, plus `horizontalAlign`/`verticalAlign`. The shadow is
+  shading element 8, a drop shadow, not a stroke on every word. The centred
+  bundled reference stores justification `3`. A dry run lists
+  `editableInputs`. Per-word scale and cue in/out transitions stay refused.
+
+### Documentation
+
+- `docs/guides/subtitle-track-editing.md`, `docs/SKILL.md`, and the control
+  panel setup note describe the new controls and the Node install.
+
+### Validation
+
+- Subtitle codec suites and the frame-capture, subtitle-gap, and Node-provision
+  unit tests pass.
+- Live page-restore harness on Resolve Studio 19.1.3.7 (`--repeat 1`): captures
+  from every page restored format, path, mode, and page, with no warnings once
+  a render path existed. The open session was 19.1, not 21.1.
+- The shadow and alignment round-trip was checked against the bundled Word
+  Highlight export from Studio 21.1. A live dry run on a track created with
+  `AddTrack("subtitle")` stops before those controls: that track has no Fusion
+  preset holder.
+
+## What's New in v4.13.7 — Missing-media relink works for paths written on another OS
+
+Lands #294, the follow-up to #293 for the Windows/macOS path work tracked in
+#278. A project moved between macOS and Windows keeps the paths the other OS
+wrote, so the missing-media diagnosis and relink plan now go by the path's own
+form.
+
+### Fixed
+
+- **Wanted basename (`src/server.py`, `_missing_media_diagnosis` and
+  `_build_relink_plan`)**: both used `os.path.basename`, which splits on the
+  running OS's separator only. On macOS the basename of `E:\DCIM\P1047043.MOV`
+  was the whole string, so a bounded search could never match. Both now split
+  on `/` and `\`.
+- **Volumes from another OS**: after #293, `E:\` on macOS (or `/Volumes/X` on
+  Windows) counted as an unmounted volume. That skipped the relink search and
+  advised mounting a volume this OS can never mount. Such roots are now flagged
+  `foreign_os_path` on volume, folder, item and candidate rows, and are never
+  probed with `isdir`. They report the new
+  `primary_cause="foreign_os_path"`, which advises searching the approved roots,
+  and they no longer trigger `skip_search_when_volume_missing`. A same-OS
+  unmounted volume behaves as before. When both kinds are present, the advice
+  names both.
+- **Sanitized relink plans**: with `sanitized=true`, `file_path` is dropped, so
+  the plan searched by the Resolve clip name. It now takes the basename from
+  `file_path_sanitized`, which keeps the filename.
+
+### Documentation
+
+- `docs/SKILL.md` documents `foreign_os_path`.
+
+### Validation
+
+- New `ForeignOsMediaPathTests` and basename/form tables pin the host OS, so
+  Linux, macOS and Windows CI all run both directions. Linux CI green on the PR.
+- Full offline suite and release static checks pass on macOS.
+- Diagnosis only, with no Resolve API call changed, so a live test is not
+  required.
+
 ## What's New in v4.13.6 — `drt` downgrade stamps the real Resolve build
 
 ### Fixed

package/README.md

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

package/docs/SKILL.md

@@ -422,7 +422,9 @@ Operating rules an agent must know:
   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.
+  size/position and text RGBA; highlight, outline, drop-shadow and justification
+  integers are Word Highlight-specific. The centred reference stores alignment
+  `3`. Per-word scale and cue transitions are not literal inputs and are refused.
   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.
@@ -1806,7 +1808,11 @@ missing volume roots, sample basenames, and a recommended next step. If a source
 volume such as a camera card is not mounted, `build_relink_plan` skips broad
 search by default and reports `skip_reason="missing_source_volume_not_mounted"`;
 mount the volume or pass `skip_search_when_volume_missing=false` only when a
-bounded scan of approved roots is intentional.
+bounded scan of approved roots is intentional. Paths written on another OS
+(`E:\...` on macOS, `/Volumes/...` on Windows, after a project moves between
+machines) are flagged `foreign_os_path`: their volume can never be mounted
+here, so they report `primary_cause="foreign_os_path"`, do not hold back the
+search, and are matched by their own basename under the approved roots.
 
 Audio / Fairlight kernel actions (v2.14.0+) add live-tested audio state,
 mapping, voice-isolation, sync, transcription, subtitle, and Fairlight boundary

package/docs/guides/control-panel.md

@@ -205,7 +205,9 @@ created, and render time against the active tier, and the AI-ops ledger
   identity, and Media Pool inventory.
 - **MCP** — server identity, detected Resolve scripting paths, transport
   status (with a start button for the networked mode), and per-client install
-  status with one-click install/repair for every supported harness.
+  status with one-click install/repair for every supported harness. That
+  install also provisions the `resolve-advanced` Node packages the live
+  subtitle preset path imports.
 - **Storage** — the analysis root, search index, and jobs database paths and
   sizes for the active project.
 - **Tools** — runtime helpers (ffprobe, ffmpeg, Whisper backends, OpenCV)

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

@@ -53,8 +53,16 @@ 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
+specific to Word Highlight. Word Highlight also accepts its shading element 8
+as a drop shadow (`shadowEnabled`, `shadowRed`, `shadowGreen`, `shadowBlue`,
+`shadowOffset`, `shadowSoftness`, `shadowSoftnessX`, `shadowSoftnessY`) and
+`horizontalAlign` / `verticalAlign`, which write the template's justification
+integers. The centred bundled reference stores `3`. That shadow is not a stroke
+on the unhighlighted words; `outlineEnabled` and `thickness` remain the
+spoken-word outline. Per-word scale and cue in/out transitions are not literal
+inputs on this macro and are refused. A dry run's `editableInputs` lists the
+controls the holder actually accepts. 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
@@ -238,11 +246,14 @@ 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
-based on common literal Template TextPlus inputs for subtitle templates;
-highlight and outline controls are specific to Word Highlight.
+Colour channels are 0–1, `outlineEnabled` and `shadowEnabled` are 0 or 1,
+`size` is Fusion's normalised text size (not points), `position` is Fusion
+Center `[x,y]`, `shadowOffset` is an `[x,y]` pair in that same space,
+`thickness` is the template's HOutlineThickness value, and `horizontalAlign`
+/ `verticalAlign` are the template's justification integers (the centred
+reference stores 3). Parameter editing is based on common literal Template
+TextPlus inputs for subtitle templates; highlight, outline, shadow and
+alignment 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

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.13.6"
+VERSION = "4.14.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
@@ -1232,6 +1232,42 @@ def advanced_is_bootable(project_dir):
     return True
 
 
+def provision_advanced_node_deps(project_dir, dry_run=False):
+    """Install resolve-advanced runtime deps when the tree is present and they are not.
+
+    The live subtitle path imports those packages from this checkout. Registering
+    the advanced server as an npx fallback does not install them for that path
+    (issue #297). Returns a short status string and never raises: a missing npm
+    must not abort the Python install.
+    """
+    project_dir = Path(project_dir)
+    advanced = project_dir / "resolve-advanced"
+    if not (advanced / "package.json").is_file():
+        return "advanced server tree is not present"
+    if advanced_is_bootable(project_dir):
+        return "already installed"
+    command = "npm install --omit=dev --omit=optional"
+    if dry_run:
+        return f"would run {command}"
+    npm = "npm.cmd" if platform.system() == "Windows" else "npm"
+    try:
+        result = subprocess.run(
+            [npm, "install", "--omit=dev", "--omit=optional", "--no-audit", "--no-fund"],
+            cwd=str(advanced),
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        return f"npm was not found; from {advanced} run: {command}"
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip().splitlines()
+        tail = detail[-1] if detail else f"exit {result.returncode}"
+        return f"npm install failed: {tail}. From {advanced} run: {command}"
+    if not advanced_is_bootable(project_dir):
+        return f"npm install finished but Node dependencies are still missing. From {advanced} run: {command}"
+    return "installed"
+
+
 def build_advanced_npx_entry(python_path=None):
     """Fallback advanced entry that runs from the npm package, not this tree.
 
@@ -2278,6 +2314,15 @@ def main():
     else:
         print(f"  Server:    {yellow(str(server_path))} {dim('(file not found — check path)')}")
 
+    # The live subtitle preset path imports jszip from this tree. The advanced
+    # server entry can fall back to npx; that fallback does not install the
+    # packages this checkout's timeline_ai call actually loads (issue #297).
+    node_deps = provision_advanced_node_deps(project_dir, dry_run=args.dry_run)
+    if node_deps in ("installed", "already installed"):
+        print(f"  Node deps: {green(node_deps)}")
+    else:
+        print(f"  Node deps: {yellow(node_deps)}")
+
     # ══════════════════════════════════════════════════════════════════════
     # STEP 4: Configure MCP Clients
     # ══════════════════════════════════════════════════════════════════════

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "4.13.6",
+  "version": "4.14.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

@@ -22,6 +22,17 @@ const inputs = z.object({
   highlightRed: rgb.optional(), highlightGreen: rgb.optional(), highlightBlue: rgb.optional(),
   outlineRed: rgb.optional(), outlineGreen: rgb.optional(), outlineBlue: rgb.optional(),
   outlineEnabled: z.union([z.literal(0), z.literal(1)]).optional(), thickness: z.number().min(0).max(1).optional(),
+  // Word Highlight shading element 8 (a drop shadow) and its justification
+  // integers. The centred bundled reference stores 3. Per-word scale and cue
+  // in/out are not literal inputs on this macro and stay refused.
+  shadowEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+  shadowRed: rgb.optional(), shadowGreen: rgb.optional(), shadowBlue: rgb.optional(),
+  shadowOffset: z.tuple([z.number().min(-1).max(1), z.number().min(-1).max(1)]).optional(),
+  shadowSoftness: z.number().min(0).max(20).optional(),
+  shadowSoftnessX: z.number().min(0).max(20).optional(),
+  shadowSoftnessY: z.number().min(0).max(20).optional(),
+  horizontalAlign: z.number().int().min(0).max(8).optional(),
+  verticalAlign: z.number().int().min(0).max(8).optional(),
 }).strict();
 export const subtitleSchemas = {
   list_subtitle_presets: z.object({ ...target, timeline: z.string().optional() }).strict(),

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

@@ -76,6 +76,8 @@ export async function editSubtitleTimeline({ source, output, track = 1, inputs =
   exported.zip.file(exported.entry, xml);
   const buffer = await exported.zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
   await fs.writeFile(output, buffer, { flag: 'wx' });
-  return { output, templateId: chosen.decoded.templateId, before: before?.decoded.inputs ?? null, after: decodePreset(patched).inputs,
+  const decoded = decodePreset(patched);
+  return { output, templateId: chosen.decoded.templateId, before: before?.decoded.inputs ?? null, after: decoded.inputs,
+    editableInputs: decoded.editableInputs,
     verification: 'exported_preset_readback', restart_required: false };
 }

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

@@ -108,7 +108,7 @@ export const projectDbTool = {
     'Beyond-the-API Project.db patches: list_folders, rename_folder, set_folder_color, list_clips, set_clip_marks, relayout_node_graphs, list_subtitle_styles, set_subtitle_style (basic track font/position, NOT animation presets). ' +
     'Subtitle actions: list_subtitle_presets(projectName|projectDb, timeline?) reads linked Fusion animation presets; ' +
     'copy_subtitle_preset(sourceProject|sourceProjectDb, sourceTimeline, sourceTrack?, projectName|projectDb, timeline, track?, replace?, inputs?); ' +
-    'set_subtitle_preset(projectName|projectDb, timeline, track?, inputs) edits Word Highlight controls: font, fontStyle, size, position:[x,y], textRed/Green/Blue/Alpha, highlightRed/Green/Blue, outlineRed/Green/Blue, outlineEnabled:0|1, thickness; RGB 0..1. ' +
+    'set_subtitle_preset(projectName|projectDb, timeline, track?, inputs) edits Word Highlight controls: font, fontStyle, size, position:[x,y], textRed/Green/Blue/Alpha, highlightRed/Green/Blue, outlineRed/Green/Blue, outlineEnabled:0|1, thickness, shadowEnabled:0|1, shadowRed/Green/Blue, shadowOffset:[x,y], shadowSoftness/X/Y, horizontalAlign/verticalAlign (justification integers; the centred reference stores 3); RGB 0..1. Shadow is shading element 8, a drop shadow, not a stroke on every word. Per-word scale and cue transitions are not literal inputs and are refused. ' +
     'list_captions(projectName|projectDb, timeline, track?) returns text, start/end and words plus originalWords; ' +
     'write_captions(same selectors, add:[{text,start,end,words:[{text,start,end}]}]?, replace:[{id,text,start,end,words}]?, delete:[id]?, templateCaptionId?) edits/adds/deletes in one transaction; all times are absolute timeline frames, end exclusive, caption frames integers, word frames may be fractional; ' +
     'check_captions(same selectors, maxCharacters?:24) flags timing gaps/zero lengths/overflow heuristics. Subtitle track defaults to 1. ' +

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

@@ -12,6 +12,14 @@ const INPUTS = {
   highlightRed: 'HighlightColorRed', highlightGreen: 'HighlightColorGreen', highlightBlue: 'HighlightColorBlue',
   outlineRed: 'HOutlineR', outlineGreen: 'HOutlineG', outlineBlue: 'HOutlineB',
   outlineEnabled: 'HOutline', thickness: 'HOutlineThickness',
+  // Shading element 8 on the bundled Word Highlight is a drop shadow (offset
+  // plus softness), not a stroke on the unhighlighted words. HOutline remains
+  // the spoken-word outline. The centred reference stores justification 3.
+  shadowEnabled: 'Enabled8',
+  shadowRed: 'Red8', shadowGreen: 'Green8', shadowBlue: 'Blue8',
+  shadowOffset: 'Offset8',
+  shadowSoftness: 'Softness8', shadowSoftnessX: 'SoftnessX8', shadowSoftnessY: 'SoftnessY8',
+  horizontalAlign: 'HorizontalJustificationNew', verticalAlign: 'VerticalJustificationNew',
 };
 const COMMON_INPUTS = Object.fromEntries(Object.entries(INPUTS).filter(([key]) =>
   ['font', 'fontStyle', 'size', 'position', 'textRed', 'textGreen', 'textBlue', 'textAlpha', 'textFillMode'].includes(key)));
@@ -116,7 +124,7 @@ function setPresetInputs(blob, changes) {
   const range = inputTable(u.text);
   let inputs = u.text.slice(range.start, range.end);
   for (const [key, value] of Object.entries(changes)) {
-    const name = INPUTS[key];
+    const name = mapping[key];
     if (!name) throw new Error(`unknown preset input ${key}`);
     const r = inputRange(inputs, name), replacement = `${name} = Input { Value = ${literal(key === 'textFillMode' ? 0 : value)}, }, `;
     if (r) {

package/src/analysis_dashboard.py

@@ -15025,7 +15025,15 @@ def _mcp_install_payload(client_id: str) -> Dict[str, Any]:
         )
     except Exception as exc:
         return {"success": False, "error": str(exc)}
-    return {"success": bool(ok), "message": message, "client_id": client_id}
+    # Same gap as install.py: writing the client entry does not install the
+    # Node packages the live subtitle preset path imports (issue #297).
+    node_deps = "not provisioned"
+    try:
+        project_dir = os.path.dirname(os.path.dirname(os.path.abspath(paths["server_path"])))
+        node_deps = installer.provision_advanced_node_deps(project_dir)
+    except Exception as exc:
+        node_deps = f"npm install failed: {exc}"
+    return {"success": bool(ok), "message": message, "client_id": client_id, "node_deps": node_deps}
 
 
 def _mcp_uninstall_payload(client_id: str) -> Dict[str, Any]:

package/src/granular/common.py

@@ -91,7 +91,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.13.6"
+VERSION = "4.14.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.13.6"
+VERSION = "4.14.0"
 
 import base64
 import os
@@ -21,6 +21,7 @@ import inspect
 import json
 import logging
 import math
+import ntpath
 import platform
 import re
 import shutil
@@ -8465,6 +8466,43 @@ def _media_path_parts(text: str) -> List[str]:
     return [part for part in re.split(r"[\\/]", text) if part]
 
 
+def _media_path_basename(path: Any) -> str:
+    # `os.path.basename` splits on the running OS's separator only, so on macOS
+    # the basename of `E:\DCIM\P1047043.MOV` is the whole string and a search
+    # for it can never match. Go by the path's own form instead.
+    parts = _media_path_parts(str(path or ""))
+    return parts[-1] if parts else ""
+
+
+def _media_path_form(path: Any) -> Optional[str]:
+    # "windows" for a drive letter or UNC share, "posix" for a /-rooted path,
+    # None for a relative path, which says nothing about the OS that wrote it.
+    text = str(path or "")
+    if text.startswith("\\\\") or _WINDOWS_DRIVE_PATH.match(text):
+        return "windows"
+    if text.startswith("/"):
+        return "posix"
+    return None
+
+
+def _host_media_path_form() -> str:
+    return "windows" if os.name == "nt" else "posix"
+
+
+def _media_path_is_foreign(path: Any) -> bool:
+    # A path another OS wrote: `E:\` on macOS, `/Volumes/X` on Windows. Its
+    # volume can never be mounted on this machine, so "mount it" is the wrong
+    # advice; the media has to be found under a root this OS can see.
+    form = _media_path_form(path)
+    return form is not None and form != _host_media_path_form()
+
+
+def _media_path_dirname(text: str) -> str:
+    # ntpath understands drive letters, UNC shares and both separators on any
+    # OS; posix-form paths keep the running OS's own dirname.
+    return ntpath.dirname(text) if _media_path_form(text) == "windows" else os.path.dirname(text)
+
+
 def _sanitize_media_path(path: Any, *, keep_filename: bool = True) -> Optional[str]:
     if not path:
         return None
@@ -8508,7 +8546,8 @@ def _missing_media_diagnosis(missing_rows: List[Dict[str, Any]]) -> Dict[str, An
     for row in missing_rows:
         file_path = row.get("file_path")
         media_pool_item_id = row.get("media_pool_item_id") or file_path or row.get("name")
-        basename = os.path.basename(str(file_path or row.get("media_pool_item_name") or row.get("name") or ""))
+        basename = _media_path_basename(file_path or row.get("media_pool_item_name") or row.get("name"))
+        foreign = _media_path_is_foreign(file_path)
         item = by_media_pool_item.setdefault(
             str(media_pool_item_id),
             {
@@ -8517,6 +8556,7 @@ def _missing_media_diagnosis(missing_rows: List[Dict[str, Any]]) -> Dict[str, An
                 "wanted_basename": basename,
                 "file_path_sanitized": _sanitize_media_path(file_path),
                 "volume_root_sanitized": _sanitize_media_path(_media_path_volume_root(file_path), keep_filename=False),
+                "foreign_os_path": foreign,
                 "timeline_occurrence_count": 0,
                 "track_refs": [],
             },
@@ -8536,7 +8576,11 @@ def _missing_media_diagnosis(missing_rows: List[Dict[str, Any]]) -> Dict[str, An
                 volume_root,
                 {
                     "volume_root_sanitized": _sanitize_media_path(volume_root, keep_filename=False),
-                    "mounted": os.path.isdir(volume_root),
+                    # Never probed: this OS reads the name as something else
+                    # (`/Volumes/X` is a folder on the current Windows drive,
+                    # `E:\` a relative name on macOS).
+                    "mounted": False if foreign else os.path.isdir(volume_root),
+                    "foreign_os_path": foreign,
                     "clip_count": 0,
                     "sample_basenames": [],
                 },
@@ -8545,13 +8589,14 @@ def _missing_media_diagnosis(missing_rows: List[Dict[str, Any]]) -> Dict[str, An
             if basename and basename not in volume_row["sample_basenames"] and len(volume_row["sample_basenames"]) < 8:
                 volume_row["sample_basenames"].append(basename)
 
-        folder = os.path.dirname(str(file_path)) if file_path else ""
+        folder = _media_path_dirname(str(file_path)) if file_path else ""
         if folder:
             folder_row = missing_folders.setdefault(
                 folder,
                 {
                     "folder_sanitized": _sanitize_media_path(folder, keep_filename=False),
-                    "exists": os.path.isdir(folder),
+                    "exists": False if foreign else os.path.isdir(folder),
+                    "foreign_os_path": foreign,
                     "clip_count": 0,
                     "sample_basenames": [],
                 },
@@ -8563,14 +8608,28 @@ def _missing_media_diagnosis(missing_rows: List[Dict[str, Any]]) -> Dict[str, An
     unique_items = list(by_media_pool_item.values())
     missing_volume_rows = list(missing_volumes.values())
     missing_folder_rows = list(missing_folders.values())
-    absent_volumes = [row for row in missing_volume_rows if not row.get("mounted")]
+    foreign_volumes = [row for row in missing_volume_rows if row.get("foreign_os_path")]
+    absent_volumes = [row for row in missing_volume_rows if not row.get("mounted") and not row.get("foreign_os_path")]
     absent_folders = [row for row in missing_folder_rows if not row.get("exists")]
+    foreign_labels = ", ".join(row["volume_root_sanitized"] for row in foreign_volumes[:3])
     primary_cause = "none"
     recommended_next_step = "No offline media detected."
     if absent_volumes:
         primary_cause = "volume_not_mounted"
         labels = ", ".join(row["volume_root_sanitized"] for row in absent_volumes[:3])
         recommended_next_step = f"Mount the missing volume(s): {labels}."
+        if foreign_volumes:
+            recommended_next_step += (
+                f" Paths written on another operating system ({foreign_labels}) cannot be mounted here;"
+                " relink those from approved media roots by basename."
+            )
+    elif foreign_volumes:
+        primary_cause = "foreign_os_path"
+        recommended_next_step = (
+            f"These media paths were written on another operating system, so their volume(s)"
+            f" ({foreign_labels}) cannot be mounted here. Search approved media roots for the wanted basenames"
+            " (build_relink_plan), then relink with media_pool.safe_relink."
+        )
     elif absent_folders:
         primary_cause = "folder_not_found"
         labels = ", ".join(row["folder_sanitized"] for row in absent_folders[:3])
@@ -8731,8 +8790,10 @@ def _build_relink_plan(tl, p: Dict[str, Any]):
         return _err(f"search_roots must be existing directories: {invalid}")
     missing_report = _detect_missing_media(tl, p)
     diagnosis = missing_report.get("diagnosis") or _missing_media_diagnosis(missing_report.get("missing", []))
+    # A volume another OS wrote can never be mounted here, so it never holds the
+    # search back: approved roots are the only place its media can turn up.
     if _coerce_bool(p.get("skip_search_when_volume_missing"), True) and any(
-        not row.get("mounted") for row in diagnosis.get("missing_volumes", [])
+        not row.get("mounted") and not row.get("foreign_os_path") for row in diagnosis.get("missing_volumes", [])
     ):
         return {
             "success": True,
@@ -8749,7 +8810,10 @@ def _build_relink_plan(tl, p: Dict[str, Any]):
     candidates = []
     rows_by_basename: Dict[str, List[Dict[str, Any]]] = {}
     for row in missing_report.get("missing", []):
-        wanted = os.path.basename(str(row.get("file_path") or row.get("media_pool_item_name") or row.get("name") or ""))
+        # A sanitized report drops `file_path`; its sanitized form keeps the
+        # filename and the root's form, which is all the search needs.
+        path = row.get("file_path") or row.get("file_path_sanitized")
+        wanted = _media_path_basename(path or row.get("media_pool_item_name") or row.get("name"))
         if wanted:
             rows_by_basename.setdefault(wanted, []).append(row)
     for wanted, rows in rows_by_basename.items():
@@ -8763,6 +8827,7 @@ def _build_relink_plan(tl, p: Dict[str, Any]):
             {
                 **row,
                 "wanted_basename": wanted,
+                "foreign_os_path": _media_path_is_foreign(row.get("file_path") or row.get("file_path_sanitized")),
                 "timeline_occurrence_count": len(rows),
                 "candidate_paths": [] if _coerce_bool(p.get("sanitize_paths")) or _coerce_bool(p.get("sanitized")) else matches,
                 "candidate_paths_sanitized": sanitized_matches,
@@ -15234,6 +15299,18 @@ def _render_target_dir(proj, teardown: List[str]) -> Optional[str]:
     return target if isinstance(target, str) and target else None
 
 
+def _timeline_subtitle_count(tl) -> int:
+    """Subtitle tracks on `tl`, or 0 when the count cannot be read."""
+    try:
+        count = tl.GetTrackCount("subtitle")
+    except Exception:
+        return 0
+    try:
+        return int(count or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
 def _playhead_frame_render(proj, tl, p: Dict[str, Any],
                            teardown: Optional[List[str]] = None):
     """Render exactly one frame — the only frame-accurate capture route.
@@ -15258,7 +15335,9 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any],
       - TargetDir is read off a throwaway render job before the capture changes
         it (_render_target_dir) and written back afterwards. A project that
         has never had a render target has nothing to read, and Resolve cannot
-        clear one once set, so there it is left on the capture's folder.
+        clear one once set, so the capture's folder is left in place. It is
+        not deleted: Deliver pointing at a removed path raises the modal
+        "Render Path Inaccessible".
       - CustomName is never written. It can be neither read nor cleared (an
         empty one is refused on 19.1.3.7), so the capture renders under
         whatever name the project already produces, into a folder of its own,
@@ -15411,13 +15490,10 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any],
         # to read it from.
         original_target = _render_target_dir(proj, teardown)
         codecs = proj.GetRenderCodecs("JPEG" if fmt == "jpg" else fmt.upper()) or {}
-        codec = list(codecs.values())[0] if codecs else fmt
-        if not proj.SetCurrentRenderFormatAndCodec(fmt, codec):
-            return _err(
-                f"Resolve refused render format {fmt!r} with codec {codec!r}",
-                code="RENDER_FORMAT_REFUSED", category="api_error",
-                state={"format": fmt, "codec": codec},
-            )
+        codec = list(codecs.values())[0] if isinstance(codecs, dict) and codecs else fmt
+        # The output folder goes in BEFORE the format change. Switching format
+        # while TargetDir is missing raises Resolve's modal "Render Path
+        # Inaccessible — Please select a valid render path." (issue #296).
         applied = proj.SetRenderSettings({
             "TargetDir": folder,
             "MarkIn": frame,
@@ -15433,6 +15509,13 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any],
                 state={"frame": frame},
             )
         range_pinned = True
+        fmt_id, codec_id = _canonical_render_format_codec(proj, fmt, codec)
+        if not proj.SetCurrentRenderFormatAndCodec(fmt_id, codec_id):
+            return _err(
+                f"Resolve refused render format {fmt_id!r} with codec {codec_id!r}",
+                code="RENDER_FORMAT_REFUSED", category="api_error",
+                state={"format": fmt_id, "codec": codec_id},
+            )
         job = proj.AddRenderJob()
         if not job:
             return _err("AddRenderJob returned nothing", code="RENDER_JOB_FAILED", category="api_error")
@@ -15485,6 +15568,14 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any],
         else:
             with open(src_path, "rb") as handle:
                 data = handle.read()
+        if _timeline_subtitle_count(tl):
+            teardown.append(
+                "This still does not include the subtitle track. A capture "
+                "cannot turn subtitle burn-in on for one frame and put the "
+                "previous ExportSubtitle setting back: there is no "
+                "GetRenderSettings, and on Resolve 19 those keys are accepted "
+                "and then ignored."
+            )
         return Image(data=data, format=out_format)
     finally:
         if job:
@@ -15513,9 +15604,12 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any],
             # A failed restore leaves the Deliver page on the capture's format
             # and codec, which the user's next render would silently inherit.
             # This runs in a teardown path, so it is logged rather than raised.
+            # The getter reports descriptions ('H.264'); the setter wants ids
+            # ('H264') and refuses the description (issue #296).
+            restore_fmt, restore_codec = _canonical_render_format_codec(
+                proj, original_fc.get("format"), original_fc.get("codec"))
             try:
-                restored_fc = proj.SetCurrentRenderFormatAndCodec(
-                    original_fc.get("format"), original_fc.get("codec"))
+                restored_fc = proj.SetCurrentRenderFormatAndCodec(restore_fmt, restore_codec)
             except Exception as exc:
                 restored_fc, restore_exc = False, exc
             else:
@@ -15523,12 +15617,12 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any],
             if not restored_fc:
                 logger.warning(
                     "frame capture could not restore the render format/codec to %s/%s: %s",
-                    original_fc.get("format"), original_fc.get("codec"),
+                    restore_fmt, restore_codec,
                     restore_exc or "SetCurrentRenderFormatAndCodec returned False",
                 )
                 teardown.append(
                     "The render format/codec was left on the capture's "
-                    f"({fmt}); restoring {original_fc.get('format')}/{original_fc.get('codec')} "
+                    f"({fmt}); restoring {restore_fmt}/{restore_codec} "
                     "failed, so the next render job would inherit it."
                 )
         # The mark range: put the user's own range back when they had one, and
@@ -15575,23 +15669,43 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any],
         # The output folder, when there was one to read. Without this the
         # user's next render job inherits a temporary folder that the cleanup
         # just below removes.
+        # Deleting the folder Deliver is still pointed at raises the modal
+        # "Render Path Inaccessible". Remove it only after the user's own path
+        # is back. A project that never had one cannot have it cleared, so the
+        # folder stays (issue #296).
+        target_moved = False
         if range_pinned and original_target:
             try:
                 target_restored = bool(proj.SetRenderSettings({"TargetDir": original_target}))
                 target_exc = None
             except Exception as exc:
                 target_restored, target_exc = False, exc
-            if not target_restored:
+            if target_restored:
+                target_moved = True
+            else:
                 logger.warning(
                     "frame capture could not restore the render output folder to %s: %s",
                     original_target, target_exc or "SetRenderSettings returned False",
                 )
                 teardown.append(
                     "The render output folder was left on the capture's temporary "
-                    f"folder; restoring {original_target!r} failed. Set it again with "
-                    "render(action='set_settings', params={'settings': {'TargetDir': ...}})."
+                    f"folder ({folder}); restoring {original_target!r} failed. "
+                    "The folder was kept so Deliver is not left pointing at a "
+                    "missing path, which raises Resolve's 'Render Path Inaccessible' "
+                    "dialog. Set it again with render(action='set_settings', "
+                    "params={'settings': {'TargetDir': ...}})."
                 )
-        _discard_still_staging(folder)
+        elif range_pinned:
+            teardown.append(
+                "The render output folder was left on the capture's temporary "
+                f"folder ({folder}). This project had no render path to put back, "
+                "and removing the folder would leave Deliver pointing at a missing "
+                "path, which raises Resolve's 'Render Path Inaccessible' dialog. "
+                "Set a render path with render(action='set_settings', "
+                "params={'settings': {'TargetDir': ...}})."
+            )
+        if target_moved or not range_pinned:
+            _discard_still_staging(folder)
         try:
             os.rmdir(base)  # only ever succeeds when nothing else is using it
         except OSError:
@@ -20445,6 +20559,25 @@ def _render_codec_id(proj, fmt: str, codec: str, formats: Optional[Dict[str, Any
     return _render_codec_id_from_codecs(codecs, codec)
 
 
+def _canonical_render_format_codec(proj, fmt, codec):
+    """Ids `SetCurrentRenderFormatAndCodec` accepts.
+
+    GetCurrentRenderFormatAndCodec and the Deliver page labels are descriptions.
+    On 19.1 and 21.0.4, ('mp4', 'H.264') is refused and ('mp4', 'H264') is
+    accepted. An unrecognized value passes through for Resolve to reject.
+    """
+    if not isinstance(fmt, str) or not isinstance(codec, str) or not fmt or not codec:
+        return fmt, codec
+    try:
+        formats = _render_formats(proj)
+    except Exception:
+        formats = {}
+    if not isinstance(formats, dict):
+        formats = {}
+    format_id = _render_format_id_from_formats(formats, fmt)
+    return format_id, _render_codec_id(proj, format_id, codec, formats)
+
+
 def _render_codecs(proj, fmt: str, formats: Optional[Dict[str, Any]] = None):
     try:
         return _ser(proj.GetRenderCodecs(_render_format_id(proj, fmt, formats)) or {})
@@ -27119,7 +27252,9 @@ def timeline_frame(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
     route switches back and reads the page to confirm it. If any restore does
     not take, the image is followed by {"warnings": [...]} naming what was left
     changed and the call that puts it back (an error result carries the same
-    "warnings" key). No warnings block means every restore was confirmed.
+    "warnings" key). No warnings block means every restore was confirmed. A
+    timeline with a subtitle track also gets a warning: the still does not
+    include that track.
     """
     p = _params(params)
     if action == "capture":
@@ -27150,9 +27285,11 @@ def timeline_frame(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
                 "CustomName": True,
             },
             "render_settings_caveat": (
-                "A project that has never had a render TargetDir is left with the "
-                "capture's temporary folder as its TargetDir."
+                "A project that has never had a render TargetDir keeps the capture's "
+                "temporary folder. Removing it would leave Deliver pointing at a "
+                "missing path, which raises Resolve's 'Render Path Inaccessible' dialog."
             ),
+            "subtitles_included": False,
         }
         _, tl, err = _get_tl()
         if err:
@@ -27187,7 +27324,11 @@ def timeline_ai(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
       set_subtitle_preset(track?, inputs?, preset?, preset_reference?, reference_track?, revision_name?, dry_run?, templates_archive?)
         Apply an installed subtitle preset and common literal font/style, size,
         position and text RGBA controls with Resolve kept open. Word Highlight
-        also supports mapped highlight/outline colours and thickness. Native
+        also supports mapped highlight/outline colours and thickness, its drop
+        shadow (shadowEnabled, shadowRed/Green/Blue, shadowOffset, shadowSoftness
+        and the X/Y pair) and horizontalAlign/verticalAlign justification
+        integers (the centred reference stores 3). Per-word scale and cue
+        in/out transitions are not literal inputs and are refused. Native
         export -> codec -> native import as a selected revision; original retained.
         Word Highlight and Lollipop have bundled references; other installed
         presets are captured natively in a temporary title timeline. Full IDs

package/src/utils/subtitle_live.py

@@ -16,6 +16,34 @@ from src.utils.title_library import find_subtitle_preset
 
 ROOT = Path(__file__).resolve().parents[2]
 BRIDGE = ROOT / "scripts" / "edit_subtitle_timeline.mjs"
+_ADVANCED = ROOT / "resolve-advanced"
+
+
+def subtitle_codec_gap():
+    """Why the live subtitle codec cannot run, or None when its Node deps are present.
+
+    timeline_ai set_subtitle_preset imports jszip from resolve-advanced/. The
+    advanced MCP entry falls back to npx when those packages are missing; this
+    path does not, so a fresh installer/control-panel setup that never ran
+    npm install fails with ERR_MODULE_NOT_FOUND (issue #297).
+    """
+    manifest_path = _ADVANCED / "package.json"
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return f"The subtitle preset codec is not present at {_ADVANCED}"
+    missing = []
+    for dep in (manifest.get("dependencies") or {}):
+        if not (_ADVANCED / "node_modules" / dep).is_dir() and not (ROOT / "node_modules" / dep).is_dir():
+            missing.append(dep)
+    if not missing:
+        return None
+    shown = ", ".join(missing[:8])
+    extra = f" (+{len(missing) - 8} more)" if len(missing) > 8 else ""
+    return (
+        f"Subtitle preset editing needs Node packages that are not installed ({shown}{extra}). "
+        f"From {_ADVANCED} run: npm install --omit=dev --omit=optional"
+    )
 
 
 def _capture_installed_preset(resolve, project, preset, output):
@@ -67,6 +95,9 @@ def set_subtitle_preset(resolve, project, timeline, params, safe_dir):
     node = shutil.which("node")
     if not node:
         return {"success": False, "error": "Node.js is required for the subtitle preset codec"}
+    gap = subtitle_codec_gap()
+    if gap:
+        return {"success": False, "error": gap}
     # The dispatcher coerces strings before the safety-gated helper is entered.
     dry_run = params.get("dry_run", False)
     if not isinstance(dry_run, bool):
@@ -116,7 +147,12 @@ def set_subtitle_preset(resolve, project, timeline, params, safe_dir):
                                    capture_output=True, text=True, encoding="utf-8", errors="replace",
                                    timeout=60, check=False)
         if completed.returncode:
-            raise RuntimeError(completed.stderr.strip() or "Subtitle codec failed")
+            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)
         # The codec's output file is private staging, removed after success.
         patch.pop("output", None)