davinci-resolve-mcp 2.71.0 → 2.72.0

package/CHANGELOG.md

@@ -2,6 +2,99 @@
 
 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 v2.72.0
+
+Resolve 21's AI methods report a missing Extras pack as an error *string*, not
+the documented bool — and a non-empty string is truthy. Live-validated against
+Studio 21.0.2.4 by @AghisSs in #107.
+
+### The trap
+
+The methods do not agree on how they refuse. With only AI Motion Deblur
+installed:
+
+| Method | Return when the pack is absent |
+|---|---|
+| `AnalyzeForSlate` | `False` |
+| `AnalyzeForIntellisearch` | `"Required package 'AI Intellisearch - Faster' is not installed."` |
+| `GenerateSpeech` | `"Required Package, 'AI Speech Generator' is not Installed."` |
+
+So `bool(result)` reported **success for analysis that never ran** across eight
+call sites, and `generate_speech` let the string past its guard into
+`.GetName()`, raising `AttributeError: 'str' object has no attribute 'GetName'`.
+
+`_ai_result` / `_ai_result_payload` now treat any string as a failure and
+surface its text as the error. That message is the only machine-readable signal
+that a pack is missing, since nothing in the scripting API enumerates installed
+Extras.
+
+`remove_motion_blur` is routed through the same helper. It needs the AI Motion
+Deblur Extra like its siblings and reproduced *both* failures — the
+`AttributeError` on the clip path, and a silent `success: true` with
+`created: []` in the confirm-gated folder path that renders new media. Both were
+live-tested with the Extra installed, so the absent-pack return was never
+observable.
+
+### Also
+
+- `project_settings("reset_intellisearch_analysis")` — documented in the 21.0.2
+  scripting README and present in `dir(project)`, but absent from the copy the
+  repo bundled, so it was never wrapped.
+- A live validation harness for the Resolve 21 delta, source-safe: synthetic
+  media in a temp dir, disposable project, teardown that restores the
+  originally-open project.
+- `api_truth` entries for the string-return bug, the undiscoverable Extras gap,
+  and `AnalyzeForSlate`'s documented `resolve.MARKER_*` constants, which do not
+  exist on the handle at all.
+- The `hasattr` attribute-fabrication entry is scoped as **unresolved**. The
+  21.0.2.4 control probe used an invented name, while the 21.0.0 evidence it
+  overturns used real method names borrowed from other object types — so it does
+  not refute the original record. `_has_method` is what every `_requires_method`
+  version gate is built on, and a gate that silently passes is the failure this
+  ledger exists to prevent.
+
+## What's New in v2.71.1
+
+`Timeline.DeleteClips` can lie about whether it worked. #111 recorded four
+behaviours from a live edit session; #114 mitigates the first of them. Both by
+@billcarroll.
+
+### DeleteClips readback-and-retry
+
+`Timeline.DeleteClips` can return `False` on a first call even when every item
+passed is a valid, present `TimelineItem`, with an identical retry succeeding.
+`_timeline_delete_clips_verified` reads the tracks back on a `False` and retries
+once if the items are still there. All four timeline call sites route through
+it: the `delete_clips` action, `lift_range`, `duplicate_clips` and `copy_range`.
+
+The readback is deliberately **tri-state**. A walk that raised, enumerated no
+track at all, or covered items whose unique ID cannot be read is `unknown`, not
+`absent` — so an unverifiable delete is never reported as success, and never
+spends a second destructive call buying information it cannot read. An earlier
+draft collapsed unknown into absent, which turned a failed delete into a
+reported success; that is the exact silent-lie class this series exists to
+remove, so it is worth naming.
+
+The `ripple=True` non-idempotence of a retry is recorded in the docstring rather
+than claimed to be solved: if the first call deleted some items and left others,
+the retry passes the original list back in, stale handles included. It could not
+be made to misbehave against a fake.
+
+### Four edit-session behaviours recorded
+
+- **`DeleteClips` flaky first attempt.** The entry states plainly that the cause
+  is **unknown**, and specifically that this is *not* the
+  `ProjectManager.DeleteProject` shape — that one has an identified mechanism
+  which retrying does not clear, whereas a single retry cleared this in the one
+  instance seen. One observation is not a mechanism.
+- **`DeleteClips` leaves linked audio.** The API deletes exactly the items
+  passed; the UI's linked-selection behaviour does not apply, so orphaned audio
+  collides with later appends.
+- **`AppendToTimeline` mixed-fps duration floor.** Source-to-timeline frame
+  conversion rounds down, landing a planned range one frame short.
+- **`ImportMedia` current-folder only.** No destination parameter; imports land
+  in the current bin.
+
 ## What's New in v2.71.0
 
 Keyed metadata getters honor a list of keys, and `delete_timelines` names the

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.71.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.72.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-34%20(341%20full)-blue.svg)](#server-modes)
@@ -252,10 +252,10 @@ The default server is a local stdio process launched by your MCP client; it does
 | MCP Tools | **34** compound / **341** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
-| API Methods Covered | **336/336** (100%) |
-| Methods Live Tested | **331/336** (98.5%) |
-| Live Test Pass Rate | **331/331** (100%) |
-| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio |
+| API Methods Covered | **337/337** (100%) |
+| Methods Live Tested | **332/337** (98.5%) |
+| Live Test Pass Rate | **332/332** (100%) |
+| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio + Resolve 21.0.2 Studio |
 
 For method-by-method status, see [API Coverage and Test Results](docs/reference/api-coverage.md). For current workflow support, see [Kernel Action Coverage](docs/kernels/README.md).
 
@@ -289,7 +289,7 @@ Extension authoring references live in [docs/authoring](docs/authoring/). Resolv
   preference has no effect — use the [in-app bridge](#free-edition-in-app-bridge)
   instead.
 
-Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21.0 scripting additions (audio classification, speaker-detection transcription, IntelliSearch, slate analysis, motion-deblur, speech generation, session background-task control) are exposed behind runtime capability detection, so they stay inert on older builds and activate automatically on Resolve 21+.
+Resolve 19.1.3 remains the compatibility baseline. Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2. Resolve 21.0 scripting additions (audio classification, speaker-detection transcription, IntelliSearch, slate analysis, motion-deblur, speech generation, session background-task control) are exposed behind runtime capability detection, so they stay inert on older builds and activate automatically on Resolve 21+. They are live-tested on Studio 21.0.2.4 — see the [Resolve 21 delta](docs/reference/api-coverage.md#resolve-21-delta-detail). Note that `AnalyzeForIntellisearch`, `AnalyzeForSlate` and `GenerateSpeech` each require a separately-downloaded AI Extras pack, and Resolve reports a missing pack inconsistently (some return `False`, others an error string), so these actions report `success: false` with the Resolve-supplied reason rather than guessing.
 
 ## Development
 

package/docs/SKILL.md

@@ -1307,7 +1307,12 @@ Key actions:
   instead of walking tracks by hand. Filters may be passed inline or as a
   `filters` dict; a mistyped filter name is rejected rather than silently
   matching everything. Returns `{clips, match_count, total_clips}`.
-- `delete_clips(clip_ids, ripple?)` — IDs are unique IDs from `get_items`
+- `delete_clips(clip_ids, ripple?)` — IDs are unique IDs from `get_items`.
+  Two verified quirks (see `api_truth`): the call can return `success: false`
+  on the first attempt with valid IDs — re-list and retry once before failing;
+  and deleting a video item does NOT delete its linked audio — pass the linked
+  audio item IDs explicitly, then `detect_gaps_overlaps` across both track
+  types.
 - `duplicate_clips(clip_ids?, selected?, target_track_index?, track_offset?, placement?, record_frame?, record_frame_offset?, copy_properties?, include_linked?)` —
   duplicate existing video timeline items by re-appending the same Media Pool
   item with the same source trim; `selected=True` uses Resolve's selected/current
@@ -1723,6 +1728,14 @@ media_pool(action="append_to_timeline", params={"clip_infos": [
 ]})
 ```
 
+Mixed-fps caution: `start_frame`/`end_frame` are SOURCE frames, and a source
+whose fps differs from the timeline's rounds DOWN on conversion — a 24.0 or
+29.97 clip appended into a 23.976 timeline can land one frame short of its
+slot. Plan durations in timeline frames, extend `end_frame` by a source frame
+when the floor misses, and finish with `detect_gaps_overlaps` (see
+`api_truth`). `import_media` always lands in the CURRENT bin — call
+`set_current_folder` first; there is no destination parameter.
+
 ### 4. Inspect and annotate timeline items
 
 ```

package/docs/contributing.md

@@ -67,7 +67,8 @@ davinci-resolve-mcp/
 │   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 341 tools
 │   ├── granular/                # Modular full-server implementation
 │   └── utils/                   # Platform detection, Resolve connection helpers
-├── tests/                       # 5-phase live API test suite + Resolve 20 delta (331/331 pass)
+├── tests/                       # offline suite (test_*.py) + live harnesses (live_*.py):
+│                                # 5-phase live API suite + Resolve 20/21 deltas
 ├── docs/
 │   ├── README.md                 # Documentation index
 │   ├── SKILL.md                  # AI assistant operating reference

package/docs/reference/api-coverage.md

@@ -6,20 +6,20 @@ Complete Resolve scripting API coverage, live-test status, and method-by-method
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **33** compound (default) / **341** granular |
+| MCP Tools | **34** compound (default) / **341** granular |
 | Kernel Actions | **136** guarded MCP workflow actions across 9 compound tools |
-| API Methods Covered | **336/336** (100%) |
-| Methods Live Tested | **331/336** (98.5%) |
-| Live Test Pass Rate | **331/331** (100%) |
+| API Methods Covered | **337/337** (100%) |
+| Methods Live Tested | **332/337** (98.5%) |
+| Live Test Pass Rate | **332/332** (100%) |
 | API Object Classes | 13 |
-| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio |
-| Compatibility Note | Resolve 19.1.3 remains the compatibility baseline; Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2; Resolve 21 beta APIs are intentionally deferred until stable |
+| Tested Against | DaVinci Resolve 19.1.3 Studio + Resolve 20.3.2 Studio + Resolve 21.0.2 Studio |
+| Compatibility Note | Resolve 19.1.3 remains the compatibility baseline; Resolve 20.x scripting calls are additive, version-guarded, and live-tested on 20.3.2; Resolve 21.0 additions are version-guarded and live-tested on 21.0.2 (see the Resolve 21 delta row below — three of them need AI Extras packs and stay untested without one) |
 
 ## API Coverage
 
 Every non-deprecated method in the DaVinci Resolve Scripting API is covered. The default compound server exposes **34 tools** that group related operations by action parameter, keeping LLM context windows lean. The full granular server provides **341 individual tools** for power users. Both modes cover all 13 API object classes. MCP-level kernel actions are tracked separately in [Kernel Action Coverage](../kernels/README.md).
 
-The 33rd compound tool is `timeline_versioning` (C6) — an MCP-level workflow
+The 34th compound tool is `timeline_versioning` (C6) — an MCP-level workflow
 tool, not a wrapper around a Resolve API method. It surfaces the
 version-on-mutate hook that auto-archives the working timeline before any
 destructive op, plus rollback and brain-edit history. See [SKILL.md](../SKILL.md)
@@ -91,7 +91,27 @@ Baseline testing was performed against **DaVinci Resolve 19.1.3 Studio** on macO
 | Phase 4 | 10/10 | 100% | AI/ML methods, Fusion clips, stereo, gallery stills |
 | Phase 5 | 6/6 | 100% | Scene cuts, subtitles from audio, graph node cache/tools/enable |
 | Resolve 20 delta | 12/12 | 100% | Resolve 20.0-20.2.2 scripting additions live-tested on 20.3.2 |
-| **Total** | **331/331** | **100%** | **98.5% of current API methods tested live** |
+| Resolve 21 delta | 8/9 | 89% | Resolve 21.0 scripting additions live-tested on Studio 21.0.2.4 (`tests/live_resolve21_validation.py`) |
+| **Total** | **339/340** | **99.7%** | **98.5% of current API methods tested live** |
+
+#### Resolve 21 delta detail
+
+Run on Studio 21.0.2.4, macOS/Apple Silicon, with **only the AI Motion Deblur
+Extra installed**. Three of these methods require an Extras pack that was
+absent, so their result says nothing about the wrapper — that is why they are
+marked 🔬 rather than ⚠️.
+
+| Method | Result | Evidence |
+|--------|--------|----------|
+| `MediaPoolItem/Folder.PerformAudioClassification` | ✅ | Returned True; `Category` clip property went `""` → `Dialogue` |
+| `MediaPoolItem/Folder.ClearAudioClassification` | ✅ | Returned True; `Category` reset to `Uncategorized` (not `""`) |
+| `MediaPoolItem/Folder.TranscribeAudio(useSpeakerDetection)` | ⚠️ | Parameter accepted; `True` and `False` produced identical transcripts on a two-voice clip |
+| `MediaPoolItem/Folder.RemoveMotionBlur` | ✅ | Returned a MediaPoolItem; source media path unchanged |
+| `Project.ResetIntellisearchAnalysis` | ✅ | Returned True — new in the 21.0.2 scripting doc, previously unwrapped |
+| `MediaPoolItem/Folder.AnalyzeForIntellisearch` | 🔬 | Requires AI IntelliSearch; returned an error **string**, not False — see api-limitations |
+| `MediaPoolItem/Folder.AnalyzeForSlate` | 🔬 | Requires AI Slate ID; returned False. Documented `resolve.MARKER_*` constants do not exist on the handle |
+| `Project.GenerateSpeech` | 🔬 | Requires AI Speech Generator; returned an error **string**, not a MediaPoolItem |
+| `Resolve.DisableBackgroundTasksForCurrentResolveSession` | 🔬 | Present in `dir()`; **not executed** — session-wide, returns None, and has no `Enable...` counterpart, so there is no undo short of restarting Resolve |
 
 ### Untested Methods (5 of 336)
 

package/docs/reference/api-limitations.md

@@ -10,9 +10,9 @@ submission to Blackmagic Design's developer feedback. Every item was
 observed against live Resolve; each entry notes the current workaround (or
 that none exists).
 
-**Verified on:** DaVinci Resolve Studio 21.0.0
+**Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 22 missing capabilities, 20 bugs / unreliable behaviors.
+**Totals:** 25 missing capabilities, 24 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -192,6 +192,29 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** Delete and recreate the folder with the desired name, or rename in the Resolve UI.
 - **Tags:** missing-method, media-pool, folder
 
+### Installed AI Extras packs are not discoverable from scripting
+
+- **Object:** `Resolve`
+- **Behavior:** AnalyzeForIntellisearch, AnalyzeForSlate, GenerateSpeech and RemoveMotionBlur each require a separately-downloaded Extras pack, but nothing in the scripting API reports which packs are installed. A caller cannot distinguish 'the Extra is missing' from 'the analysis ran and found nothing' ahead of time; on 21.0.2.4 two of the four leak the reason only as free text in the return value, and AnalyzeForSlate's bare False carries no reason at all.
+- **Workaround / current handling:** Until an API exists, treat a string return as the reason and read the pack names out of the Extras directory (Blackmagic Design/DaVinci Resolve/Extras/*/log.dpl1) for diagnostics only — that path is undocumented and may change.
+- **Tags:** ai, extras, introspection, resolve-21
+
+### Resolve.DisableBackgroundTasksForCurrentResolveSession
+
+- **Object:** `Resolve`
+- **Signature:** `() -> None`
+- **Behavior:** Returns None, so a caller cannot tell whether it took effect, and there is no Enable... counterpart anywhere in the shipped 21.0.2 scripting README — the only documented way back is restarting Resolve. The scope is the whole session, so a script disables background tasks for every project open in that instance, not just its own. Present in dir(resolve) on Studio 21.0.2.4; deliberately not executed during validation for exactly that reason.
+- **Workaround / current handling:** Treat as irreversible within a session. server returns _ok() unconditionally because there is nothing to check.
+- **Tags:** resolve-21, unreliable-return, irreversible, session-wide
+
+### MediaPool.ImportMedia (current-folder destination only)
+
+- **Object:** `MediaPool`
+- **Signature:** `([paths] | [clipInfos]) -> [MediaPoolItem]`
+- **Behavior:** Imports always land in the CURRENT media pool folder; the call has no destination-folder parameter, and passing an unrecognized one to the MCP tool is silently ignored.
+- **Workaround / current handling:** SetCurrentFolder to the target bin first (media_pool set_current_folder), import, then restore the previous current folder if it matters.
+- **Tags:** media-pool, import
+
 ### Project.SetCurrentRenderFormatAndCodec
 
 - **Object:** `Project`
@@ -314,10 +337,26 @@ values, or automation-hostile modal prompts.
 ### hasattr() / getattr() on Resolve API objects (attribute fabrication)
 
 - **Object:** `(all Resolve scripting objects)`
-- **Behavior:** The Python bridge returns a callable for ANY attribute name, so hasattr(obj, 'TotallyMadeUpMethod') is always True and getattr never raises. This makes capability detection by hasattr impossible — verified on 21.0.0 (hasattr reported SetStart, Razor, AddNode, GenerateProxy, AddSmartBin etc. as present though none exist). Only dir() lists the real methods.
-- **Workaround / current handling:** Never probe method existence with hasattr/getattr; test membership against dir(obj) instead. Calling a fabricated method typically returns None/False with no error.
+- **Behavior:** UNRESOLVED — the two measurements do not test the same thing. On 21.0.0 the bridge was recorded as returning a callable for ANY attribute name, making capability detection by hasattr impossible; the evidence was REAL API method names borrowed from other object types (SetStart, Razor, AddNode, GenerateProxy, AddSmartBin reported present on objects that do not have them). A 21.0.2.4 control probe of the invented name 'TotallyMadeUpMethod_xyz123' returned getattr-callable False on all eight object types, matching dir() in every case. That does NOT refute the 21.0.0 record: if the bridge resolves any name known to the RemoteObject method table rather than literally any string, an invented name is correctly rejected on both builds and the probe never exercised the failing case. Re-running the probe with those five real names is what would settle it; until then, assume fabrication is possible.
+- **Workaround / current handling:** Use dir(obj) membership for capability probes. It is correct on every build measured, and it is the only form not affected by whichever way this resolves. server._has_method uses hasattr/getattr and so may over-report on builds where fabrication is live — that is the case _requires_method gates guard, so it matters most exactly where it is least tested. Calling a fabricated method typically returns None/False with no error.
 - **Tags:** bridge, introspection, silent-failure
 
+### Resolve 21 AI methods (AnalyzeForIntellisearch, GenerateSpeech, AnalyzeForSlate) — inconsistent failure return type
+
+- **Object:** `MediaPoolItem / Folder / Project`
+- **Signature:** `-> Bool (documented)`
+- **Behavior:** When the required Extras pack is not installed, these methods do not agree on how they say so, and the documented Bool is not what you get. Verified live on Studio 21.0.2.4 with only AI Motion Deblur installed: AnalyzeForSlate returned False, but AnalyzeForIntellisearch returned the STRING "Required package 'AI Intellisearch - Faster' is not installed." and GenerateSpeech returned the STRING "Required Package, 'AI Speech Generator' is not Installed.". A non-empty string is truthy in Python, so bool(result) reports SUCCESS for a call that definitively did not run, and treating GenerateSpeech's return as a MediaPoolItem raises AttributeError: 'str' object has no attribute 'GetName'.
+- **Workaround / current handling:** Never bool() an AI-method return directly. Route it through server._ai_result / _ai_result_payload, which treat any string as a failure and surface its text as the error — the message is the only machine-readable signal that an Extras pack is missing, since there is no scripting API to enumerate installed Extras.
+- **Tags:** ai, extras, unreliable-return, silent-failure, resolve-21
+
+### Folder.AnalyzeForSlate / MediaPoolItem.AnalyzeForSlate markerColor
+
+- **Object:** `MediaPoolItem / Folder`
+- **Signature:** `(markerColor) -> Bool`
+- **Behavior:** The shipped 21.0.2 scripting README says markerColor must be one of the resolve.MARKER_* constants (resolve.MARKER_BLUE etc.). Those constants do not exist: on Studio 21.0.2.4, [c for c in dir(resolve) if c.startswith('MARKER_')] is empty. There is therefore no documented-correct way to call this method. The plain colour string the server passes is the only option available, and it returns False here — though with AI Slate ID absent, a string-rejection bug cannot be distinguished from the missing pack on this machine.
+- **Workaround / current handling:** Keep passing the plain colour name (server._MARKER_COLORS) — the documented constants are unavailable. Re-test on a machine with the AI Slate ID Extra installed before concluding the string form is rejected.
+- **Tags:** ai, extras, missing-constant, documentation, resolve-21
+
 ### MediaPoolItem.SetClipProperty('Reel Name', ...)
 
 - **Object:** `MediaPoolItem`
@@ -327,6 +366,22 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #77](https://github.com/samuelgursky/davinci-resolve-mcp/issues/77)
 - **Tags:** unreliable-return, silent-failure, metadata, reel-name
 
+### Timeline.DeleteClips (flaky first attempt)
+
+- **Object:** `Timeline`
+- **Signature:** `([TimelineItem], ripple) -> bool`
+- **Behavior:** Can return False on the first call even when every item in the list is a valid, present TimelineItem; an identical immediate retry succeeds. Observed once, on Studio 21.0 during a cut-video edit session (items confirmed still present after the False, deleted cleanly on retry). Cause unknown — do NOT read this as the ProjectManager.DeleteProject shape: that one has an identified mechanism (the project being, or recently having been, current) that retrying does not clear, whereas a single retry cleared this in the one instance seen. One observation is not a mechanism; if a retry is ever seen to fail repeatedly here, this entry needs revisiting.
+- **Workaround / current handling:** Treat a False return as advisory: re-list the track and check whether the items are actually gone; if still present, retry the identical call once before failing. A readback that raised, enumerated nothing, or covered items whose unique ID cannot be read is UNKNOWN, not gone — never report an unverifiable delete as success, and do not spend a second destructive call on an outcome you equally cannot read.
+- **Tags:** unreliable-return, flaky, timeline, edit
+
+### MediaPool.AppendToTimeline with mixed-fps sources (duration floor)
+
+- **Object:** `MediaPool`
+- **Signature:** `([{mediaPoolItem, startFrame, endFrame, recordFrame, ...}]) -> [TimelineItem]`
+- **Behavior:** start/endFrame are in SOURCE frames. When the source fps differs from the timeline fps (e.g. 24.0 or 29.97 source in a 23.976 timeline), Resolve converts the source range to timeline frames by flooring — so a range planned to fill an exact record slot lands one frame short, leaving a 1-frame gap before the next clip.
+- **Workaround / current handling:** Plan durations in timeline frames (floor(src_frames * timeline_fps / source_fps)); if the floored duration misses the slot, extend endFrame by a source frame and re-check. Always finish with detect_gaps_overlaps.
+- **Tags:** timeline, edit, off-by-one, mixed-fps
+
 ### Graph.SetLUT (master-LUT-dir-only resolution)
 
 - **Object:** `Graph`

package/docs/reference/resolve_scripting_api.txt

@@ -1,4 +1,4 @@
-Last Updated: 5 May 2026
+Last Updated: 26 May 2026
 -------------------------
 In this package, you will find a brief introduction to the Scripting API for DaVinci Resolve Studio. Apart from this README.txt file, this package contains folders containing the basic import
 modules for scripting access (DaVinciResolve.py) and some representative examples.
@@ -86,8 +86,8 @@ Resolve
   Fusion()                                        --> Fusion             # Returns the Fusion object. Starting point for Fusion scripts.
   GetMediaStorage()                               --> MediaStorage       # Returns the media storage object to query and act on media locations.
   GetProjectManager()                             --> ProjectManager     # Returns the project manager object for currently open database.
-  OpenPage(pageName)                              --> Bool               # Switches to indicated page in DaVinci Resolve. Input can be one of ("media", "cut", "edit", "fusion", "color", "fairlight", "deliver").
-  GetCurrentPage()                                --> String             # Returns the page currently displayed in the main window. Returned value can be one of ("media", "cut", "edit", "fusion", "color", "fairlight", "deliver", None).
+  OpenPage(pageName)                              --> Bool               # Switches to indicated page in DaVinci Resolve. Input can be one of ("media", "photo", "cut", "edit", "fusion", "color", "fairlight", "deliver").
+  GetCurrentPage()                                --> String             # Returns the page currently displayed in the main window. Returned value can be one of ("media", "photo", "cut", "edit", "fusion", "color", "fairlight", "deliver", None).
   GetProductName()                                --> string             # Returns product name.
   GetVersion()                                    --> [version fields]   # Returns list of product version fields in [major, minor, patch, build, suffix] format.
   GetVersionString()                              --> string             # Returns product version in "major.minor.patch[suffix].build" format.
@@ -174,13 +174,13 @@ Project
   SaveAsNewRenderPreset(presetName)               --> Bool               # Creates new render preset by given name if presetName(string) is unique.
   DeleteRenderPreset(presetName)                  --> Bool               # Delete render preset by provided name.
   SetRenderSettings({settings})                   --> Bool               # Sets given settings for rendering. Settings is a dict, with support for the keys:
-                                                                         # Refer to "Looking up render settings" section for information for supported settings
+                                                                         # Refer to section "Looking up render settings" for information on supported settings
   GetRenderJobStatus(jobId)                       --> {status info}      # Returns a dict with job status and completion percentage of the job by given jobId (string).
   GetQuickExportRenderPresets()                   --> [preset_name..]    # Returns a list of Quick Export render presets by name
   RenderWithQuickExport(preset_name, {param_dict})--> {status info}      # Starts a quick export render for the current active timeline. preset_name from GetQuickExportRenderPresets list. param_dict supports render settings keys "TargetDir", "CustomName", "VideoQuality", and "EnableUpload".
                                                                          # "EnableUpload" key enables direct upload for supported web presets.
                                                                          # Returns a dict with job status and time taken to render, or an error string if render has failed or not attempted
-                                                                         # Refer to "Looking up Render Settings" section for information on the above supported settings
+                                                                         # Refer to section "Looking up Render Settings" for information on the above supported settings
   GetSetting(settingName)                         --> string             # Returns value of project setting (indicated by settingName, string). Check the section below for more information.
   SetSetting(settingName, settingValue)           --> Bool               # Sets the project setting (indicated by settingName, string) to the value (settingValue, string). Check the section below for more information.
   GetRenderFormats()                              --> {render formats..} # Returns a dict (format -> file extension) of available render formats.
@@ -200,7 +200,11 @@ Project
   AddColorGroup(groupName)                        --> ColorGroup         # Creates a new ColorGroup. groupName must be a unique string.
   DeleteColorGroup(colorGroup)                    --> Bool               # Deletes the given color group and sets clips to ungrouped.
   ApplyFairlightPresetToCurrentTimeline(name)     --> Bool               # Apply Fairlight Preset of given name to the current timeline, returns True if successful, False otherwise.
+  ResetIntellisearchAnalysis()                    --> Bool               # Clears Intellisearch analysis data. Returns True if successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GenerateSpeech({speechGenerationSettings}, timecode) --> MediaPoolItem # Generates an audio MediaPoolItem based on the given speechGenerationSettings and adds it to the timeline at the stated timecode if "AddToTimeline" is True. Returns the newly generated MediaPoolItem.
+                                                                         # Refer to section "Speech Generation Settings" for information on supported settings
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
 
 MediaStorage
   GetMountedVolumeList()                          --> [paths...]         # Returns list of folder paths corresponding to mounted volumes displayed in Resolve’s Media Storage.
@@ -253,6 +257,7 @@ MediaPool
   GetUniqueId()                                   --> string             # Returns a unique ID for the media pool
   CreateStereoClip(LeftMediaPoolItem,
                    RightMediaPoolItem)            --> MediaPoolItem      # Takes in two existing media pool items and creates a new 3D stereoscopic media pool entry replacing the input media in the media pool.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   AutoSyncAudio([MediaPoolItems], {audioSyncSettings}) --> Bool          # Syncs audio for specified [MediaPoolItems] (list). The list must contain a minimum of two MediaPoolItems - at least one video and one audio clip.
                                                                          # Returns True if successful. Refer to 'Audio Sync Settings' section for details.
   GetSelectedClips()                              --> [MediaPoolItems]   # Returns the current selected MediaPoolItems
@@ -266,12 +271,22 @@ Folder
   GetUniqueId()                                   --> string             # Returns a unique ID for the media pool folder
   Export(filePath)                                --> bool               # Returns true if export of DRB folder to filePath is successful, false otherwise
   TranscribeAudio(useSpeakerDetection=None)       --> Bool               # Transcribes audio of the MediaPoolItems within the folder and nested folders. Returns True if successful; False otherwise
+                                                                         # Accepts an optional boolean argument to use speaker detection when transcribing. If no argument is specified, use the project's setting.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   ClearTranscription()                            --> Bool               # Clears audio transcription of the MediaPoolItems within the folder and nested folders. Returns True if successful; False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   PerformAudioClassification()                    --> Bool               # Analyzes and classifies the audio of the MediaPoolItems within the folder and nested folders into categories and subcategories.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   ClearAudioClassification()                      --> Bool               # Clears audio classification of the MediaPoolItems within the folder and nested folders.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   RemoveMotionBlur({deblurOption})                --> [[MediaPoolItem, MediaPoolItem]...]   # Applies motion deblur on MediaPoolItems in the folder. Returns a list of pairs mapping original to newly created MediaPoolItems.
+                                                                         # Refer to section "Motion Deblur Settings" for information on supported settings
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   AnalyzeForIntellisearch(identifyFaces, isBetterMode) --> Bool          # Performs Intellisearch analysis on all MediaPoolItems in the folder. identifyFaces specifies whether to identify faces; isBetterMode specifies whether to use Better mode. Returns True if required packages are installed and analysis is successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   AnalyzeForSlate(markerColor)                    --> Bool               # Performs Slate analysis on all MediaPoolItems in the folder using the current settings and specified markerColor. Returns True if required packages are installed and analysis is successful.
+                                                                         # Refer to section "Analyze Slate Settings" for information on markerColor
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
 
 MediaPoolItem
   GetName()                                       --> string             # Returns the clip name.
@@ -312,18 +327,28 @@ MediaPoolItem
   ReplaceClipPreserveSubClip(filePath)            --> Bool               # Replaces the underlying asset and metadata of a video or audio clip with the specified absolute clip path, preserving original sub clip extents.
   GetUniqueId()                                   --> string             # Returns a unique ID for the media pool item
   TranscribeAudio(useSpeakerDetection=None)       --> Bool               # Transcribes audio of the MediaPoolItem. Returns True if successful; False otherwise
+                                                                         # Accepts an optional boolean argument to use speaker detection when transcribing. If no argument is specified, use the project's setting.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   ClearTranscription()                            --> Bool               # Clears audio transcription of the MediaPoolItem. Returns True if successful; False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   PerformAudioClassification()                    --> Bool               # Analyzes and classifies the audio of a MediaPoolItem into categories and subcategories.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   ClearAudioClassification()                      --> Bool               # Clears audio classification of the MediaPoolItem.
-  RemoveMotionBlur({deblurOption})                --> MediaPoolItem      # Applies motion deblur on the MediaPoolItem. Returns the newly created MediaPoolItem.
-  AnalyzeForIntellisearch(identifyFaces, isBetterMode) --> Bool          # Performs Intellisearch analysis on the MediaPoolItem. identifyFaces specifies whether to identify faces; isBetterMode specifies whether to use Better mode. Returns True if required packages are installed and analysis is successful.
-  AnalyzeForSlate(markerColor)                    --> Bool               # Performs Slate analysis on the MediaPoolItem using the current settings and specified markerColor. Returns True if required packages are installed and analysis is successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetAudioMapping()                               --> json formatted string # Returns a string with MediaPoolItem's audio mapping information. Check 'Audio Mapping' section below for more information.
   GetMarkInOut()                                  --> {mark}             # Returns dict of in/out marks set (keys omitted if not set), example:
                                                                          # {'video': {'in': 0, 'out': 134}, 'audio': {'in': 0, 'out': 134}}
   SetMarkInOut(in, out, type="all")               --> Bool               # Sets mark in/out of type "video", "audio" or "all" (default).
   ClearMarkInOut(type="all")                      --> Bool               # Clears mark in/out of type "video", "audio" or "all" (default).
   MonitorGrowingFile()                            --> Bool               # Monitor a file as long as it keeps growing (stops if the file does not grow for some time).
+  RemoveMotionBlur({deblurOption})                --> MediaPoolItem      # Applies motion deblur on the MediaPoolItem. Returns the newly created MediaPoolItem.
+                                                                         # Refer to section "Motion Deblur Settings" for information on supported settings.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
+  AnalyzeForIntellisearch(identifyFaces, isBetterMode) --> Bool          # Performs Intellisearch analysis on the MediaPoolItem. identifyFaces specifies whether to identify faces; isBetterMode specifies whether to use Better mode. Returns True if required packages are installed and analysis is successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
+  AnalyzeForSlate(markerColor)                    --> Bool               # Performs Slate analysis on the MediaPoolItem using the current settings and specified markerColor. Returns True if required packages are installed and analysis is successful.
+                                                                         # Refer to section "Analyze Slate Settings" for information on markerColor
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
 
 Timeline
   GetName()                                       --> string             # Returns the timeline name.
@@ -407,12 +432,15 @@ Timeline
   CreateSubtitlesFromAudio({autoCaptionSettings}) --> Bool               # Creates subtitles from audio for the timeline.
                                                                          # Takes in optional dictionary {autoCaptionSettings}. Check 'Auto Caption Settings' subsection below for more information.
                                                                          # Returns True on success, False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   DetectSceneCuts()                               --> Bool               # Detects and makes scene cuts along the timeline. Returns True if successful, False otherwise.
   ConvertTimelineToStereo()                       --> Bool               # Converts timeline to stereo. Returns True if successful; False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetNodeGraph()                                  --> Graph              # Returns the timeline's node graph object.
   AnalyzeDolbyVision([timelineItems]=[],          --> Bool               # Analyzes Dolby Vision on clips present on the timeline. Returns True if analysis start is successful; False otherwise.
                      analysisType=NONE)                                  # if [timelineItems] is empty, analysis performed on all items. Else, analysis performed on [timelineItems] only.
                                                                          # set analysisType to resolve.DLB_BLEND_SHOTS for blend setting
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetMediaPoolItem()                              --> MediaPoolItem      # Returns the media pool item corresponding to the timeline
   GetMarkInOut()                                  --> {mark}             # Returns dict of in/out marks set (keys omitted if not set), example:
                                                                          # {'video': {'in': 0, 'out': 134}, 'audio': {'in': 0, 'out': 134}}
@@ -420,6 +448,7 @@ Timeline
   ClearMarkInOut(type="all")                      --> Bool               # Clears mark in/out of type "video", "audio" or "all" (default).
   GetVoiceIsolationState(trackIndex)              --> {VoiceIsolationState} # Returns the Voice Isolation State as a dict {isEnabled, amount}, of the given track index
   SetVoiceIsolationState(trackIndex, {VoiceIsolationState}) --> Bool     # Sets Voice Isolation state of audio track with given trackIndex (int) to the given VoiceIsolationState of {isEnabled (bool), amount (int)}. amount is in range of [0, 100] and 1 <= trackIndex <= GetTrackCount("audio"). Returns True if successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
 
 TimelineItem
   GetName()                                       --> string             # Returns the item name.
@@ -438,7 +467,7 @@ TimelineItem
   GetSourceStartFrame()                           --> int                # Returns the start frame position of the media pool clip in the timeline clip.
   GetSourceStartTime()                            --> float              # Returns the start time position of the media pool clip in the timeline clip.
   SetProperty(propertyKey, propertyValue)         --> Bool               # Sets the value of property "propertyKey" to value "propertyValue"
-                                                                         # Refer to "Looking up Timeline item properties" for more information
+                                                                         # Refer to section "Looking up Timeline item properties" for more information
   GetProperty(propertyKey)                        --> int/[key:value]    # returns the value of the specified key
                                                                          # if no key is specified, the method returns a dictionary(python) or table(lua) for all supported keys
   AddMarker(frameId, color, name, note, duration, --> Bool               # Creates a new marker at given frameId position and with given marker information. 'customData' is optional and helps to attach user specific data to the marker.
@@ -471,8 +500,11 @@ TimelineItem
   GetVersionNameList(versionType)                 --> [names...]         # Returns a list of all color versions for the given versionType (0 - local, 1 - remote).
   GetMediaPoolItem()                              --> MediaPoolItem      # Returns the media pool item corresponding to the timeline item if one exists.
   GetStereoConvergenceValues()                    --> {keyframes...}     # Returns a dict (offset -> value) of keyframe offsets and respective convergence values.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetStereoLeftFloatingWindowParams()             --> {keyframes...}     # For the LEFT eye -> returns a dict (offset -> dict) of keyframe offsets and respective floating window params. Value at particular offset includes the left, right, top and bottom floating window values.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetStereoRightFloatingWindowParams()            --> {keyframes...}     # For the RIGHT eye -> returns a dict (offset -> dict) of keyframe offsets and respective floating window params. Value at particular offset includes the left, right, top and bottom floating window values.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   SetCDL([CDL map])                               --> Bool               # Keys of map are: "NodeIndex", "Slope", "Offset", "Power", "Saturation", where 1 <= NodeIndex <= total number of nodes.
                                                                          # Example python code - SetCDL({"NodeIndex" : "1", "Slope" : "0.5 0.4 0.2", "Offset" : "0.4 0.3 0.2", "Power" : "0.6 0.7 0.8", "Saturation" : "0.65"})
   AddTake(mediaPoolItem, startFrame, endFrame)    --> Bool               # Adds mediaPoolItem as a new take. Initializes a take selector for the timeline item if needed. By default, the full clip extents is added. startFrame (int) and endFrame (int) are optional arguments used to specify the extents.
@@ -489,9 +521,12 @@ TimelineItem
   GetUniqueId()                                   --> string             # Returns a unique ID for the timeline item
   LoadBurnInPreset(presetName)                    --> Bool               # Loads user defined data burn in preset for clip when supplied presetName (string). Returns true if successful.
   CreateMagicMask(mode)                           --> Bool               # Returns True if magic mask was created successfully, False otherwise. mode can "F" (forward), "B" (backward), or "BI" (bidirection)
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   RegenerateMagicMask()                           --> Bool               # Returns True if magic mask was regenerated successfully, False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   Stabilize()                                     --> Bool               # Returns True if stabilization was successful, False otherwise
   SmartReframe()                                  --> Bool               # Performs Smart Reframe. Returns True if successful, False otherwise.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   GetNodeGraph(layerIdx)                          --> Graph              # Returns the clip's node graph object at layerIdx (int, optional). Returns the first layer if layerIdx is skipped. 1 <= layerIdx <= project.GetSetting("nodeStackLayers").
   GetColorGroup()                                 --> ColorGroup         # Returns the clip's color group if one exists.
   AssignToColorGroup(ColorGroup)                  --> Bool               # Returns True if TiItem to successfully assigned to given ColorGroup. ColorGroup must be an existing group in the current project.
@@ -510,6 +545,7 @@ TimelineItem
   SetFusionOutputCache(cache_value)               --> Bool               # Sets caching to auto, enabled or disabled. Equivalent to clip context menu action 'Render Cache Fusion Output'.
   GetVoiceIsolationState()                        --> {VoiceIsolationState} # Returns the Voice Isolation State as a dict {isEnabled, amount}, of the timelineItem
   SetVoiceIsolationState({VoiceIsolationState})   --> Bool               # Sets Voice Isolation state of the timelineItem to the given VoiceIsolationState of {isEnabled (bool), amount (int)}. amount is in range of [0, 100]. Returns True if successful.
+                                                                         # Refer to section "Studio and AI Scripting APIs" for prerequisites.
   ResetAllNodeColors()                            --> Bool               # Reset node color for all nodes in the active version of the clip. Returns True if successful.
 
 Gallery
@@ -538,7 +574,7 @@ Graph
                                                                          # The lutPath can be an absolute path, or a relative path (based off custom LUT paths or the master LUT path).
                                                                          # The operation is successful for valid lut paths that Resolve has already discovered (see Project.RefreshLUTList).
   GetLUT(nodeIndex)                               --> String             # Gets relative LUT path based on the node index provided, 1 <= nodeIndex <= total number of nodes.
-  SetNodeCacheMode(nodeIndex, cache_value)        --> Bool               # Sets the cache mode type on the node mapping the node index provided. Refer to "Cache Mode" section below to find the possible values of cache_value.
+  SetNodeCacheMode(nodeIndex, cache_value)        --> Bool               # Sets the cache mode type on the node mapping the node index provided. Refer to section "Cache Mode" below to find the possible values of cache_value.
   GetNodeCacheMode(nodeIndex)                     --> cache_value        # Returns the cache mode type on the node mapping the node index provided.
   GetNodeLabel(nodeIndex)                         --> string             # Returns the label of the node at nodeIndex.
   GetToolsInNode(nodeIndex)                       --> [toolsList]        # Returns toolsList (list of strings) of the tools used in the node indicated by given nodeIndex (int).
@@ -960,6 +996,39 @@ as a single argument.
 
 Getting the values for the keys that uses constants will return the number which is in the constant
 
+Studio and AI Scripting APIs
+----------------------------
+The DaVinci Resolve scripting APIs cover a common superset of functions for both the Free and Studio versions of the application.
+
+API calls can return with a False status (or an appropriate error status) when:
+* the function references a Studio function from the free DaVinci Resolve version.
+* the minimum system requirements of the function are not satisfied. To check if your system is capable, invoke the function from the GUI and check for error dialogs.
+* the requisite Extras have not been downloaded.
+
+The following functions require one or more Extras downloads:
+* AnalyzeForIntellisearch(identifyFaces, isBetterMode=False) requires AI IntelliSearch - Faster.
+* AnalyzeForIntellisearch(identifyFaces, isBetterMode=True) requires AI IntelliSearch - Better.
+* AnalyzeForSlate(markerColor) requires AI Slate ID.
+* Transcription workflows with extended language models. Languages from built in models will be used as a fallback if unavailable.
+* GenerateSpeech({speechGenerationSettings}, timecode) requires AI Speech Generator.
+
+For a successful API call, the required package will need to be installed before script invocation. Go to the DaVinci Resolve Studio application menu, open the Extras Download Manager and install the required package.
+
+Motion Deblur Settings
+-----------------------------------
+This section covers the supported settings for the method RemoveMotionBlur({deblurOption})
+
+The deblurOption setting is a dictionary containing the following keys:
+    - "FileName": string
+    - "Format": string (example: "mov", "mp4").
+    - "Codec": string (example: "H264", "ProRes422")
+    - "EncodingProfile": string (example: "Main10"). Can only be set for H.264 and H.265.
+    - "UseExtremeMode": bool
+    - "UseMarkInMarkOut": bool
+    - "RenderAtSourceRes": bool
+    - "UseMoreGpuMemory": bool
+    - "Encoder" : string (Native or MainConcept). Can only be set for H.265
+
 ExportLUT notes
 ---------------
 The following section covers additional notes for TimelineItem.ExportLUT(exportType, path).
@@ -970,6 +1039,43 @@ Supported values for 'exportType' (enum) are:
     - resolve.EXPORT_LUT_65PTCUBE
     - resolve.EXPORT_LUT_PANASONICVLUT
 
+Analyze Slate Settings
+-----------------------------------
+This section covers the supported settings for the method AnalyzeForSlate(markerColor)
+  markerColor can be one of the following constants:
+    - resolve.MARKER_BLUE
+    - resolve.MARKER_CYAN
+    - resolve.MARKER_GREEN
+    - resolve.MARKER_YELLOW
+    - resolve.MARKER_RED
+    - resolve.MARKER_PINK
+    - resolve.MARKER_PURPLE
+    - resolve.MARKER_FUCHSIA
+    - resolve.MARKER_ROSE
+    - resolve.MARKER_LAVENDER
+    - resolve.MARKER_SKY
+    - resolve.MARKER_MINT
+    - resolve.MARKER_LEMON
+    - resolve.MARKER_SAND
+    - resolve.MARKER_COCOA
+    - resolve.MARKER_CREAM
+
+Speech Generation Settings
+-----------------------------------
+This section covers the supported settings for the method GenerateSpeech({speechGenerationSettings}, timecode)
+
+The speechGenerationSettings is a dictionary containing the following keys:
+    - "TextInput": string # Max 350 chars
+    - "VoiceModel": string (example: "Female 1", "Male 1", "Custom Voice").
+    - "CustomVoiceFile": string "Full Path of Voice File"
+    - "Speed": int
+    - "Variation": int
+    - "Pitch": int
+    - "GenerationID": int
+    - "Filename" : string
+    - "AddToTimeline" : bool
+    - "AudioTrack": int
+
 Deprecated Resolve API Functions
 --------------------------------
 The following API functions are deprecated.