davinci-resolve-mcp 4.14.4 → 4.15.1

package/CHANGELOG.md

@@ -2,6 +2,152 @@
 
 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.15.1 — Frame captures arrive as images on Python 3.10
+
+### Fixed
+
+- **`timeline_frame` and `timeline_markers get_thumbnail_image` return their
+  image again on Python 3.10** (#314). Both tools are declared `-> Any`. On
+  Python 3.10, FastMCP inferred a `{"result": ...}` output schema from that
+  annotation and then failed to serialize the image, so every capture
+  succeeded in Resolve and reached the client as "Unable to serialize unknown
+  type". Python 3.11 and later infer no schema, which hid the bug from CI and
+  the direct-call unit tests. Both tools now opt out of structured output;
+  their dict results still arrive as JSON text. Reported by @jo-nike.
+
+### Validation
+
+- New `tests/test_image_tool_structured_output.py` calls both tools through
+  `mcp.call_tool`. One case imports the server with Python 3.10's schema
+  inference forced, so it fails without the fix on any Python.
+- Full offline suite and release static checks. No Resolve scripting
+  behaviour changed; live Resolve test not required.
+
+## What's New in v4.15.0 — Conform-session fixes, Python doctor, restart hint
+
+Six gaps a real conform session hit on Resolve Studio 19.1.3.7, each measured
+live with rendered frames; `scripts/doctor.py` now checks the Python the
+server runs on; and a refused scripting connection with the preference already
+Local now says to restart Resolve instead of changing a setting that is
+already correct.
+
+### Fixed
+
+- **`timeline_frame capture` works on projects where rendering a frame fails.**
+  The default `quality="frame"` now exports the viewer's frame with
+  `Project.ExportCurrentFrameAsStill`: seek, read the playhead back by frame,
+  export, read the playhead again, restore it. It switches no page and writes
+  no render settings. On the project that surfaced this, the render route
+  failed every call with "AddRenderJob returned nothing"; the export worked
+  every call (3840×2160 in about 0.2 s). The single-frame render is still
+  there as `quality="render"`, used only when asked for by name. `preview` and
+  `full` now mean the export.
+- **Keyframe actions no longer crash on 19.x.** `timeline_item`
+  `get_keyframes`, `add_keyframe`, `modify_keyframe`, `delete_keyframe` and
+  `set_keyframe_interpolation` died with "'NoneType' object is not callable":
+  a live 19.1 TimelineItem exposes no keyframe methods. They now return
+  `KEYFRAME_API_UNAVAILABLE` with the live version and what to do instead.
+- **Locked tracks are named, not answered with a bare False.**
+  `timeline delete_clips` refuses with `TRACK_LOCKED` listing the locked
+  tracks before calling `DeleteClips`. A failed `media_pool
+  append_to_timeline` names locked target tracks in its error.
+- **Page switches refuse during playback.** A Color-page visit while playback
+  ran, followed by `restore_state`, hung Resolve's main thread, and every
+  later scripting call hung with it. `resolve_control open_page` and
+  `restore_state`, `gallery_stills grab_and_export`, and the page-switching
+  capture routes detect a moving playhead and refuse with `PLAYBACK_ACTIVE`.
+  `allow_during_playback=true` overrides.
+- **A refused connection with scripting already set to Local now says to
+  restart Resolve.** When Resolve was running but refused scripting
+  connections, `SCRIPTING_UNAVAILABLE` always said to set Preferences >
+  General > External scripting = Local, and implied the free edition was the
+  cause. A running Studio can refuse every connection with the preference
+  already Local until it is relaunched. The server now reads
+  `System.Scripting.Mode` from Resolve's `config.dat`, and when it is Local
+  the error leads with "Quit and relaunch DaVinci Resolve", then the existing
+  guidance. When the preference is not Local or cannot be read, the message is
+  unchanged. The error `state` has a new `scripting_preference_local` field
+  (true, false or null). The macOS `config.dat` path was checked on a real
+  Mac; the Windows and Linux paths are untested, and a wrong path reads as
+  unknown, which keeps the old message.
+
+### Added
+
+- **`timeline replace_source_range`: slip a clip to a new source range.**
+  19.x has no slip or trim API. The action rebuilds the item at the same
+  record frame through a temporary track: append the new range there,
+  CopyGrades and carry transform, crop, composite and scaling onto it, delete
+  the original, append the final copy on the original track, copy grade and
+  properties again, remove the temporary copy and track, restore the track
+  lock. Start, end and duration are verified exactly. A length that lands a
+  frame off (mixed source and timeline rates) is corrected and retried. If the
+  final placement fails, the temporary copy stays as the recovery and the
+  error says where. Confirm-token gated, archived first, `dry_run` supported;
+  a locked track needs `unlock_track=true`.
+- **`timeline_item probe_keyframe_override`.** Tells whether a property write
+  reaches the render. On a clip with Inspector keyframes, `SetProperty`
+  returns True and reads back while the render ignores it. The probe exports
+  the frame twice as a null control, nudges the property, exports again,
+  restores the property and compares. Verdict: `override`, `writes_render` or
+  `inconclusive`.
+- **`set_transform` takes `pan_px` / `tilt_px`.** Pan and Tilt scale with the
+  fitted image: Pan moves `Pan × fittedW / timelineW` px. For scale-to-fit the
+  action computes the fitted size from the clip and timeline resolutions and
+  reports the factors it used. Other scaling modes need `fitted_width` /
+  `fitted_height`.
+- **`scripts/doctor.py` checks the interpreter the server runs on.** The checks
+  live in `scripts/doctor_python_env.py`. Each problem is reported as WARN or
+  FAIL with a `Fix:` line (a `fix` key under `--json`) that gives the exact
+  command.
+  - *Python bitness.* A 32-bit Python fails, because Resolve's scripting
+    library is 64-bit only. So does a Python whose architecture the
+    `fusionscript` library was not built for. The library header (ELF, thin
+    or universal Mach-O, PE) is read directly. An Intel Python under Rosetta
+    against an arm64-only library is named as such.
+  - *Python version for Resolve.* Below 3.10 fails. 3.13+ warns unless Resolve
+    answered on this interpreter or the build is 20.3.2 or later. The build is
+    read from the live probe or, on macOS, the app bundle. 3.13+ fails when
+    the scripting module is present but will not import.
+  - *Which Python.* It reads the Claude Desktop and Codex configs. It warns
+    when a config starts the server as a bare `python3`, which a GUI app
+    resolves through a PATH that is not your shell's. It also warns when a
+    config runs a different interpreter from the one doctor checked. It lists
+    every Python on PATH and marks the server's. A venv and its base
+    interpreter count as different Pythons, because they share a binary but
+    not `sys.prefix`. It also states where `fusionscript` loads: external
+    scripting loads it into the server's interpreter, and Resolve's own
+    Scripts menu uses the Python it finds itself.
+  - The fix for a wrong interpreter moves the venv aside before re-running the
+    installer, because `install.py` reuses an existing venv.
+- **The `SCRIPTING_UNAVAILABLE` remediation points at doctor** for the case
+  where Studio is already set to Local and the cause is the server's Python.
+
+### Documentation
+
+- New api_truth entries, carried into `docs/reference/api-limitations.md`:
+  ExportCurrentFrameAsStill as the frame-capture route, the silent
+  keyframe override on SetProperty, DeleteClips on a locked track, Edit
+  transform units (reconciling the "Pan = timeline pixels" rule of thumb,
+  which holds only when the fitted width equals the timeline's), OpenPage
+  during playback, and the missing slip/trim API.
+- `docs/SKILL.md`: capture routes rewritten for the new default; Known Gotchas
+  cover playback, keyframe overrides, locked tracks, transform units and the
+  slip action.
+
+### Validation
+
+- Full Python suite: 4,221 tests, zero failures, 5 skipped. New
+  `tests/test_conform_session_gaps.py` (45 tests), an updated
+  `tests/test_playhead_frame_capture.py`, `tests/test_doctor_python_env.py`
+  (every check against fakes, with a clean 64-bit 3.12 setup as the null
+  control), and `ScriptingPreferenceTests` in `tests/test_resolve_bridge.py`.
+  No advanced-server (Node) code changed.
+- Live: the conform behaviour these fixes encode was measured in the conform
+  session itself. A live pass of the new code paths on a scratch project has
+  not run, because Resolve was in use by that session. The restart hint was
+  checked by reading this Mac's real `config.dat` (Local) and producing the
+  restart message.
+
 ## What's New in v4.14.4 — Compatible dependency updates
 
 Lands #303, #304, #305, #306, and #308. Resolves #307, #309, and #310.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.14.4-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.15.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(390%20full)-blue.svg)](#server-modes)
@@ -449,6 +449,7 @@ Extension authoring references live in [docs/authoring](docs/authoring/). Resolv
 
 - DaVinci Resolve 18.5+ on macOS, Windows, or Linux. **Studio** supports external scripting directly. The **free edition** does not — Blackmagic gates external scripting to Studio — but it is still reachable through the [in-app bridge](#free-edition-in-app-bridge), which runs inside Resolve from the ungated **Workspace ▸ Scripts** menu.
 - Python 3.10+ (3.10-3.12 is the lowest-risk range). Python 3.13/3.14 also work on recent Resolve builds (verified on Studio 20.3.2); older builds may fail to connect on 3.13+, in which case use 3.10-3.12.
+- Not connecting? `python3 scripts/doctor.py` checks the Python the server runs on and prints the exact fix for each problem: 32-bit or wrong-architecture Python, a Python too new for your Resolve build, or several Pythons where the MCP client starts the wrong one. See [Checking the Python environment](docs/install.md#checking-the-python-environment).
 - Resolve external scripting set to **Local** (Studio). On the free edition this
   preference has no effect — use the [in-app bridge](#free-edition-in-app-bridge)
   instead.

package/README.zh-CN.md

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

package/docs/SKILL.md

@@ -1890,9 +1890,16 @@ rendering — grade, Fusion, titles, transitions — rather than inferring it fr
 metadata. (For the raw camera file instead, use
 `media_analysis(action="extract_frames")`.)
 
-- `quality="frame"` (default) renders exactly that frame — the only
-  frame-accurate route. Full resolution, well under a second, works headless.
-  `preview` is the same render bounded to 1280px.
+- `quality="frame"` (default) exports exactly that frame with
+  `Project.ExportCurrentFrameAsStill`: frame-accurate, full resolution, about
+  0.2 s, **no page switch and no render settings**. The seek is read back by
+  frame before the export and the playhead is read again after it; a playhead
+  that moved means playback is running and the capture refuses
+  (`PLAYBACK_ACTIVE`). `preview` is the same export bounded to 1280px.
+- `quality="render"` renders the frame as a one-frame render job. Use it only
+  when you want that route by name: on a real project on Studio 19.1.3.7 it
+  failed every call with "AddRenderJob returned nothing" while the export
+  worked every call.
 - `quality="thumbnail"` is instant and touches nothing, but returns the **clip's**
   thumbnail — identical for every frame of that clip. Use it to see which clip is
   under the playhead, never to judge a specific frame. Needs the Color page *and*
@@ -1903,22 +1910,23 @@ metadata. (For the raw camera file instead, use
   (default), `png`, or `tif`.
 - `timecode` accepts absolute (`01:00:15:12`) or elapsed (`00:00:15:12`) time;
   `frame` is the absolute timeline frame. Omit both to capture the playhead.
+- The page-switching routes (`render`, `thumbnail`, `still`) refuse while
+  playback is running; `allow_during_playback=true` overrides.
 
-The playhead, page, current timeline and Gallery are restored. The render route
+The playhead, page, current timeline and Gallery are restored. The `render` route
 additionally touches project render settings and puts them back: render mode,
 format, codec, mark range and output folder (`TargetDir`, read off a throwaway
 render job because there is no `GetRenderSettings`). The file name
 (`CustomName`) is never written, and the render job is deleted. One gap: a
 project that has never had an output folder has none to put back, and Resolve
 cannot clear one, so it is left on the capture's temporary folder
-(`capabilities` repeats this as `render_settings_caveat`). Reach for
-`quality="thumbnail"` when zero side effects matter more than accuracy.
+(`capabilities` repeats this as `render_settings_caveat`).
 
-The render calls pull Resolve onto the Deliver page. The capture switches back
-and reads the page to confirm it. If a restore does not take (page, playhead,
-timeline, render mode, format, range or output folder), the image is followed by a
-`{"warnings": [...]}` block naming what was left changed and the call that puts
-it back. No warnings block means every restore was confirmed.
+The render calls pull Resolve onto the Deliver page. The `render` route switches
+back and reads the page to confirm it. If a restore does not take (page,
+playhead, timeline, render mode, format, range or output folder), the image is
+followed by a `{"warnings": [...]}` block naming what was left changed and the
+call that puts it back. No warnings block means every restore was confirmed.
 
 ```
 timeline_frame(action="capture", params={"timecode": "01:00:15:12", "max_width": 1280})
@@ -2493,6 +2501,42 @@ Other recorded traps ride along on results as `known_limitation` without blockin
 `RESOLVE_MCP_DISABLE_TRAP_GUARD=1` disables both behaviours.
 
 
+**Stop playback before switching pages** — On Studio 19.1.3.7 a Color-page visit
+while playback was running, followed by `restore_state`, timed out, and after
+that every scripting call hung, even a fresh connection: Resolve's main thread
+was stuck in a viewer render loop. 19.x has no transport API, so the server
+cannot stop playback. `resolve_control open_page` / `restore_state`,
+`gallery_stills grab_and_export` and the page-switching `timeline_frame` routes
+refuse with `PLAYBACK_ACTIVE` when the playhead is moving; ask the user to stop
+playback (Space or K). `allow_during_playback=true` overrides.
+
+**A transform write that reads back can still not render** — On a clip with
+Inspector keyframes (an AAF import can bring them), `SetProperty('ZoomX', v)`
+returns True and reads back `v`, and the render does not change. 19.x has no
+TimelineItem keyframe methods at all, so the `timeline_item` keyframe actions
+return `KEYFRAME_API_UNAVAILABLE` there. `timeline_item(action=
+"probe_keyframe_override")` exports the frame twice (null control), nudges the
+property, exports again and restores it; `verdict: "override"` means keyframes
+are winning. Prove sizing with frames, never with the readback.
+
+**Locked tracks fail deletes silently** — `DeleteClips` on a locked track
+returns a bare False, while `SetProperty` on the same items still works.
+`timeline delete_clips` refuses with `TRACK_LOCKED` naming the tracks.
+
+**Edit transform units** — Zoom is relative to the fitted image. Pan moves
+`Pan × fittedW / timelineW` px and Tilt `Tilt × fittedH / timelineH` px (+up),
+so Pan equals timeline pixels only when the fitted width equals the timeline's.
+A 720×1280 clip in a 4096×1716 timeline fits at 965×1716, and Pan −500 moved it
+117 px. `set_transform` takes `pan_px` / `tilt_px` and converts for
+scale-to-fit.
+
+**Slipping a clip** — there is no slip or trim API.
+`timeline(action="replace_source_range", params={"timeline_item_id": ...,
+"source_start": N})` rebuilds the item at the same record frame through a
+temporary track, carrying grade, transform, crop, composite and scaling, and
+verifies start, end and duration exactly. It is confirm-token gated, archives
+the timeline first, and refuses a locked track unless `unlock_track=true`.
+
 **Resolve API object lifetimes** — Objects like timelines, clips, and color groups
 returned by the API are live references that can become stale if the project state
 changes (e.g., the user deletes a timeline). Always re-fetch IDs after any
@@ -2572,8 +2616,9 @@ extracted from a delivered render.
 
 **Start here: `timeline_frame(action="capture")`** — Returns the frame at the
 playhead (or at any `timecode`/`frame` you name) as MCP image content, so a
-multimodal assistant can simply look at it. It renders that one frame, which is
-what makes it frame-accurate; `max_width` bounds the context cost.
+multimodal assistant can simply look at it. It exports that one frame from the
+viewer with `ExportCurrentFrameAsStill`, which is frame-accurate and switches no
+page; `max_width` bounds the context cost.
 
 ```
 timeline_frame(action="capture", params={"timecode": "01:00:15:12", "max_width": 1280})

package/docs/install.md

@@ -53,6 +53,32 @@ Model weights carry their own licences, separate from the code that loads them.
 > (`brew install python@3.12`, `pyenv install 3.12`, or python.org on Windows) and
 > point the launcher at it with `DAVINCI_RESOLVE_MCP_PYTHON=/path/to/python3.12`.
 
+### Checking the Python environment
+
+Most connection failures that are not Resolve's preferences are Python. Run the
+read-only doctor from the checkout, with any Python:
+
+```bash
+python3 scripts/doctor.py          # add --json for machine-readable output
+```
+
+Besides paths and client configs, it checks the interpreter the server runs on.
+Each problem is reported as `WARN` or `FAIL` with a `Fix:` line giving the exact
+command:
+
+| Check | Fails or warns when |
+|---|---|
+| **Python bitness** | The server's Python is 32-bit (Resolve's scripting library is 64-bit only), or its architecture is not one the `fusionscript` library is built for. The common case is an Intel Python running under Rosetta on an Apple silicon Mac. The library header is read directly, so a universal build counts as both. |
+| **Python version for Resolve** | Below 3.10 (`FAIL`, the SDK floor). On 3.13+ it warns unless Resolve answered on this interpreter or the Resolve build is 20.3.2 or later. It fails if the scripting module is present but will not import. |
+| **Client interpreter** | An MCP client config starts the server as a bare `python3` (resolved through the PATH the GUI app sees, not your shell's), or runs a different interpreter from the one doctor checked. |
+| **Pythons on PATH** | Several are installed and the first is not the server's. This is `INFO` unless a bare client command or a 32-bit or too-old Python first on PATH makes it matter. |
+| **Where fusionscript loads** | Never; this is `INFO`. External scripting loads `fusionscript` into the *server's* interpreter. Resolve's own Scripts menu, which the free-edition bridge runs from, uses a Python it finds itself. On macOS that is `PYTHON3HOME`, then `/usr/local/bin/python3`. The two need not match. |
+
+`install.py` reuses an existing venv, so the fix for a wrong interpreter moves
+the venv aside before re-running the installer with a 64-bit Python 3.12.
+`npx davinci-resolve-mcp doctor` is the installer's dry run. It does not run
+these checks.
+
 Validated live coverage is based on **DaVinci Resolve 19.1.3 Studio** for the original API surface, plus **DaVinci Resolve 20.3.2 Studio** for the Resolve 20.0-20.2.2 scripting additions. Resolve 21 beta APIs are intentionally deferred until a stable release.
 
 ## Quick Start

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 42 missing capabilities, 58 bugs / unreliable behaviors.
+**Totals:** 43 missing capabilities, 61 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -361,6 +361,13 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Read <in> as the literal source frame (Resolve reads and writes it that way), record-align it by the junction-minus-span-start offset on a -1 start, and walk -1/-1 clips with a record-order cursor. conform.snapshot ingest_xml and editorial.parse_interchange both do; the frame QC then samples each cut CLEAR of its transition windows (inside one the reference is a blend, or black for a fade).
 - **Tags:** timeline, export, xml, fcp7, transitions, silent-failure
 
+### Timeline slip / trim of an existing item (no API on 19.x)
+
+- **Object:** `Timeline`
+- **Behavior:** There is no call to slip an item's source range or trim its edges in place: no SetProperty key moves the source in-point and no Timeline method takes a new range. The only route is to delete the item and append the new range at the same record frame, which loses its grade, transform, crop and composite unless they are carried over by hand. With a source rate different from the timeline's, the appended length can come out a frame off (the AppendToTimeline mixed-fps floor) and needed a corrected endFrame and a second append.
+- **Workaround / current handling:** timeline replace_source_range: append the new range on a temporary track at the same record frame, CopyGrades onto it, carry transform/crop/composite/scaling, delete the original, append the final copy on the original track, CopyGrades from the temporary copy, re-apply the properties, delete the temporary copy, restore the track lock. Start, end and duration are verified exactly; an endFrame that lands a frame off is corrected and retried.
+- **Tags:** missing-method, timeline, edit, mixed-fps
+
 ## Bugs / Unreliable Behavior (please fix)
 
 Methods that exist but misbehave — silent failures, unreliable return
@@ -830,3 +837,27 @@ values, or automation-hostile modal prompts.
 - **Behavior:** No scriptable call produces an archive. With source media and proxies off it returns False instantly and writes nothing, for an open or a closed project and with render cache on or off. With isArchiveSrcMedia or isArchiveProxyMedia on it creates an empty directory at the target and Resolve crashes (SIGSEGV) in the same second; the call comes back through the bridge as None and every later handle is dead. Four crashes, one of them in a Blackmagic Cloud library, share identical top stack frames in Fusion script-symbol teardown on the UI thread; a separate crash in the same session during DeleteProject/LoadProject had a different stack, so the signature belongs to the archive calls. Media-flag calls crashed 4 of 4, flags-off calls 0 of 5. A file already at the target survived every case byte for byte, including a crash, so the destination is never overwritten; unsaved work in the open project is what is lost. The native defaults turn source media on, so a default call crashes Resolve. Resolve logs nothing about the False returns.
 - **Workaround / current handling:** Keep isArchiveSrcMedia and isArchiveProxyMedia off unless you have verified the build, and save every open project first. Treat False as 'nothing archived', not as a path problem: a .dra and a folder-style path fail identically. Archive from the Project Manager UI when you need a real archive.
 - **Tags:** crash, unreliable-return, silent-failure, project, reported
+
+### TimelineItem.SetProperty (Inspector-keyframed property)
+
+- **Object:** `TimelineItem`
+- **Signature:** `(propertyKey, propertyValue) -> Bool`
+- **Behavior:** On a clip that carries Edit-page (Inspector) keyframes for a transform property, as clips from an AAF import can, SetProperty('ZoomX', v) returns True and GetProperty reads v back, but the rendered frame never changes: the keyframes win at render time. Nothing in the return or the readback says so. On 19.x it cannot be detected or fixed from the API either: dir() of a live TimelineItem lists no keyframe methods (GetKeyframeCount, AddKeyframe and the rest are absent, and not in the scripting README), so the attribute is None and a call dies as "'NoneType' object is not callable".
+- **Workaround / current handling:** Prove a transform with frames, never with the return or the readback. timeline_item probe_keyframe_override exports the frame twice (null control), nudges the property, exports again and restores it; verdict 'override' means keyframes are winning. Then remove them in the Inspector, or rebuild the item from the Media Pool (timeline replace_source_range re-appends it; a fresh append should carry no Inspector keyframes, which is not yet verified by render). The timeline_item keyframe actions return KEYFRAME_API_UNAVAILABLE on builds without the methods.
+- **Tags:** silent-failure, unreliable-return, keyframes, transform, timeline, missing-method
+
+### Timeline.DeleteClips (locked track)
+
+- **Object:** `Timeline`
+- **Signature:** `([TimelineItem], ripple) -> bool`
+- **Behavior:** On a locked track DeleteClips returns a bare False and deletes nothing, with nothing to say the lock is why. The lock does not stop SetProperty: transform and other property writes on items of the same locked track still succeed, so a property edit that worked is no evidence the track is unlocked. Separate from the Edit-page gate in 'Timeline.DeleteClips (requires the Edit page; flaky first attempt)'.
+- **Workaround / current handling:** Read Timeline.GetIsTrackLocked for every track the targets sit on before deleting. timeline delete_clips refuses with TRACK_LOCKED naming the tracks; replace_source_range unlocks only with unlock_track=true and locks the track again afterwards; media_pool append_to_timeline names locked target tracks in its failure.
+- **Tags:** silent-failure, timeline, edit, track-lock
+
+### Resolve.OpenPage (during playback)
+
+- **Object:** `Resolve`
+- **Signature:** `(pageName) -> Bool`
+- **Behavior:** With playback engaged, a visit to the Color page followed by a page/playhead restore (resolve_control restore_state) timed out, and from then on EVERY scripting call hung, including a brand-new scriptapp() connection: Resolve's main thread was stuck in a viewer render loop until playback was dealt with in the GUI. The 19.x scripting API has no transport control (no Play, Stop or IsPlaying), so a script can neither stop playback first nor ask whether it is running.
+- **Workaround / current handling:** Detect playback by reading Timeline.GetCurrentTimecode twice ~0.2 s apart; a playhead that moved means the transport is running. resolve_control open_page / restore_state, gallery_stills grab_and_export and the page-switching timeline_frame routes refuse with PLAYBACK_ACTIVE (allow_during_playback=true overrides). Stop playback in the GUI (Space or K) before retrying.
+- **Tags:** hang, page-dependent, playback, missing-method

package/install.py

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

package/package.json

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

package/scripts/doctor.py

@@ -3,7 +3,10 @@
 
 Checks the checkout, Python interpreter, Resolve app and scripting-API paths,
 MCP client configs, and probes the DaVinciResolveScript bridge without
-mutating anything. Prints OK/WARN/FAIL lines (or JSON with --json) and exits
+mutating anything. The Python-environment checks (bitness against the
+fusionscript library, a Python too new for the Resolve build, several Pythons
+on PATH) live in doctor_python_env.py. Prints OK/WARN/FAIL lines, each problem
+with a `Fix:` line (or JSON with --json, where it is a `fix` key), and exits
 nonzero only when a FAIL is present.
 
 Run: `python3 scripts/doctor.py`
@@ -506,6 +509,32 @@ def extras_checks() -> list[dict[str, str]]:
     return results
 
 
+def python_env_checks(probe: dict[str, Any]) -> list[dict[str, str]]:
+    """Bitness, version-for-this-Resolve, and which-Python checks (C56).
+
+    Kept in their own module because they are the ones worth testing against
+    fakes: every input is a probe result or a file header, never the machine.
+    """
+    try:
+        sys.path.insert(0, str(REPO / "scripts"))
+        import doctor_python_env  # type: ignore
+    except Exception as exc:
+        return [{"status": "WARN", "name": "Python environment", "detail": f"checks unavailable: {exc!r}"}]
+    try:
+        return doctor_python_env.collect(
+            server_python=PYTHON,
+            lib_path=RESOLVE_LIB,
+            app_path=RESOLVE_APP,
+            repo=REPO,
+            probe=probe,
+            claude_config=CLAUDE_CONFIG,
+            codex_config=CODEX_CONFIG,
+        )
+    except Exception as exc:
+        # Never let a diagnostic tool be the thing that crashes.
+        return [{"status": "WARN", "name": "Python environment", "detail": f"checks failed: {exc!r}"}]
+
+
 def collect(
     resolve_host: str | None = None,
     resolve_timeout: float | None = None,
@@ -571,6 +600,8 @@ def collect(
             "(see 'Free-edition bridge' below).",
         )
 
+    results.extend(python_env_checks(probe))
+
     results.extend(bridge_checks(probe))
 
     results.extend(extras_checks())
@@ -601,6 +632,8 @@ def main() -> int:
     else:
         for item in results:
             print(f"[{item['status']}] {item['name']}: {item['detail']}")
+            if item.get("fix"):
+                print(f"       Fix: {item['fix']}")
 
     return 1 if any(item["status"] == "FAIL" for item in results) else 0