davinci-resolve-mcp 2.78.0 → 2.79.0

package/CHANGELOG.md

@@ -2,6 +2,128 @@
 
 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.79.0
+
+Six silent failures in the conform path, found by conforming a real Avid picture turnover
+and cross-checking every step against Resolve's own behaviour on 19.1.3. The common shape:
+a call that reports success, or reports nothing at all, and leaves you with a timeline you
+believe is right.
+
+### Fixed
+
+- **`convert_to_interchange` promised speed survives the DRT target. It does not.** The DRT
+  spec builder read four fields per event — start, duration, in, mediaFilePath — and never
+  read `speed` or `reverse`. One level down is why: the DRT clip schema has no per-clip speed
+  field at all, so there is nothing to write a retime into. A 200% clip and a reversed clip
+  both landed at 100% forward and the caller was told the conversion succeeded — inside the
+  module whose own description opens by naming "flattened retime → flag, skip-not-fake" as
+  its guarantee. Since carrying speed through was not available, the `drt` target now returns
+  **`flattened`**: one entry per retimed or reversed event, with its index, recIn, speed,
+  reverse, source and reason. It is always an array (empty when there are no retimes), so a
+  caller can tell "none to lose" from "this build is too old to report". `otio` (LinearTimeWarp)
+  and `edl` (M2) still carry retimes and are now named as the targets to use for a cut that
+  has them.
+- **The vendored FCP7 emitter produced XML that Resolve 19.1.3 imports as nothing.** Three
+  defects, all failing the same silent way — a clean-looking file and a Resolve that does
+  nothing. (1) The file def had no `<timecode>` element; Resolve rejects the ENTIRE import
+  over one absent block, not the one clip. (2) `<pathurl>` got XML escaping where it needed
+  URL escaping, now percent-encoded per segment so `/` separators survive. (3) The sequence
+  had no `<rate>`, which bisection showed was the single element standing between "no
+  timeline" and a working import. Because a *wrong* timecode block is as fatal as a missing
+  one, the emitter never guesses: clips whose media timecode is unknown emit no block and are
+  reported through `fcp7TimecodeCoverage()`, which `buildPackage` attaches as `fcp7Timecode`
+  with an `importable` flag.
+- **Importing a timeline into the never-saved `Untitled Project` silently no-opped.** Resolve
+  accepted the call, created nothing, and named no cause; the generic "Resolve created no
+  timeline" error that came back pointed at missing media and `sanitize_media` — the wrong
+  road, because the file is fine. `import_timeline_checked` now refuses before the call with
+  a remediation naming the project state. **Behaviour change:** a call that previously
+  returned a generic error now refuses earlier with a different message. The refusal is hard
+  and has no override flag, because the call cannot succeed either way.
+- **OTIO authored by `convert_to_interchange` would not import into Resolve.** Filed as a
+  scripting-API limitation; it was not one. Exporting a timeline with `EXPORT_OTIO` and
+  feeding Resolve's own file back proved the API imports OTIO fine — what it refuses is a
+  document that is valid OTIO but not Resolve-shaped. The decisive requirement is that source
+  frames be **timecode-absolute**: media starting at 01:00:00:00 has an available range at
+  frame 86400, and 0-based source offsets put the clip outside it. The emitter now mirrors
+  Resolve's own shape (Clip.2 with a `media_references` map, `available_range`, bare
+  `target_url`, `global_start_time`) and takes each event's origin via `mediaStartTcFrame` or
+  an absolute `srcTcFrame`. Events whose origin had to be assumed come back in
+  **`mediaOriginAssumed`** rather than producing a file that imports as nothing.
+- **`.otio` failures were misdiagnosed as missing media.** A `.otio` is JSON, so the
+  sanitize/relink pass cannot parse it and its advice never applied. `sanitize_media` is now
+  N/A for `.otio` as it already was for `.aaf`, and the no-timeline remediation names the
+  document's shape and the frame origin instead.
+
+### Documentation
+
+- `api_truth`: the retime entry now records that **the read side is as dead as the write
+  side** — `GetProperty('Speed'|'PlaybackSpeed'|'RetimeSpeed'|'ClipSpeed')` all return None on
+  19.1.3.7, and the keyless property dict carries no speed value at all. It also records that
+  the interchange route is closed (scalar speed filter ignored, `graphdict` dead in four
+  shapes, `reverse` dropped, in↔pproTicks inconsistency rejected in both orientations) and the
+  trap that makes it expensive to find: Resolve's own FCP7 export writes a degenerate Time
+  Remap, so `EXPORT_FCP_7_XML` cannot witness a speed. Each claim now says which Resolve
+  version it was measured on.
+- `api_truth`: **`AppendToTimeline` does not overwrite an overlapping record** — the earlier
+  item wins and the later append is dropped, leaving a silently short timeline.
+- `api_truth`: **placements from an errored append chunk are not durable across a save** — a
+  timeline verified at 573 items held 500 afterward. Every in-session read agrees with the
+  wrong number; only a post-save read catches it.
+- `api_truth`: `CreateTimelineFromClips`' clipInfo has **no track field** while
+  `AppendToTimeline`'s does, with the empty-timeline + `add_track` + per-clip append workaround.
+- `api_truth`: what Resolve's OTIO importer actually requires, and how to debug a refusal by
+  diffing against an `EXPORT_OTIO` file.
+- **New guide — `docs/guides/conforming-an-avid-aaf.md`.** Three Resolve-native mechanisms
+  measured against one real turnover; all three fail. The most convincing-looking one fails
+  worst: "Link to source camera files" links 878 of 882 items with **only 144 correct — 734
+  wrong takes, 84%** — and then renders as a fully conformed timeline, with no offline media
+  and no warning. The guide explains why the matching lands on adjacent takes and says plainly
+  that the only witness which catches it is a frame comparison against a reference.
+
+### Validation
+
+- 2417 Python unit tests, 744 Node advanced tests, plus 8 fixture-free packaging tests, all
+  green. `packaging.test.js` also no longer fails to load on a fresh clone: it read a
+  git-ignored fixture at module scope, which took the fixture-free tests down with it.
+- Live-validated on DaVinci Resolve Studio 19.1.3.7 with synthetic media: the fixed FCP7 XML
+  imports 2 items / 2 linked where the same file with its timecode blocks stripped imports
+  nothing; the authored `.otio` imports 3 items / 3 linked and re-reads frame-exact.
+
+## What's New in v2.78.1
+
+`Timeline.DeleteClips` is page-gated. Contributed by
+[@billcarroll](https://github.com/billcarroll) in
+[#117](https://github.com/samuelgursky/davinci-resolve-mcp/pull/117).
+
+### Fixed
+
+- **Every delete-capable action failed whenever the UI was left on another page.**
+  `Timeline.DeleteClips` deterministically returns False and deletes nothing off
+  the Edit page (verified: Fairlight), retries included — the readback-and-retry
+  helper from v2.71.1 handles a *flaky* False correctly, but retrying cannot clear
+  a page gate. Live verification on Studio 21.0: three identical retries against
+  132 valid, unlocked, present items all returned False with all 132 still on the
+  track; one `OpenPage("edit")` and the same call returned True and left 0. Track
+  lock and enable state were clear throughout — a page gate, not a lock.
+  `timeline` `delete_clips` / `move_clips` / `overwrite_range` / `lift_range` /
+  `apply_cuts` and `edit_engine execute_swap` now hold the Edit page for the call
+  and restore the caller's page after.
+
+The guard is serialized through `page_lock`, alongside the existing Color-page
+guard for thumbnail capture: Resolve has one globally-active page, so an
+unserialized switch-work-restore races every other page-switching operation, and
+under the threaded dispatch from v2.62.0 a concurrent thumbnail capture flipping
+to Color mid-delete would land the delete on the wrong page — reintroducing this
+same bug. `apply_cuts` holds the guard once around its loop rather than per cut,
+which would otherwise cost 2N page flips for N cuts.
+
+The `api_truth` entry is restructured into the two distinct failures now known to
+share this call: wrong page (deterministic, mechanism identified, verified) and
+flaky first attempt (one observation, cause not established — and the entry now
+records that the page state at the time was not captured, so it cannot be ruled in
+or out as the first failure in disguise).
+
 ## What's New in v2.78.0
 
 The AAF probe reports where in the *source* an event actually lives, not where it

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.78.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.79.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)
@@ -273,6 +273,7 @@ For method-by-method status, see [API Coverage and Test Results](docs/reference/
 | [Media Analysis Guide](docs/guides/media-analysis-guide.md) | Source-safe FFprobe, FFmpeg, Whisper, sidecar, and analysis-root workflows |
 | [Multicam Setup Helper Guide](docs/guides/multicam-setup-guide.md) | Stacked timeline prep, helper/API boundary, and Resolve UI conversion steps |
 | [Editorial Decision Guide](docs/guides/editorial-decision-guide.md) | Project-owned editorial craft guidance for analysis and timeline decisions |
+| [Conforming an Avid AAF](docs/guides/conforming-an-avid-aaf.md) | Why all three Resolve-native routes fail on a consolidated turnover, and which one is dangerous |
 | [Color Decision Guide](docs/guides/color-decision-guide.md) | Project-owned color correction guidance and Resolve color API boundaries |
 | [Contributing and Project Layout](docs/contributing.md) | Contribution workflow, platform support, security notes, repository structure |
 | [Security Policy](SECURITY.md) | Local stdio trust boundary, tool metadata, confirmation guidance, reporting |

package/docs/guides/conforming-an-avid-aaf.md

@@ -0,0 +1,91 @@
+# Conforming a consolidated Avid AAF: what Resolve can and cannot do for you
+
+You have an Avid picture turnover — an AAF plus consolidated media — and a folder
+of camera originals. You want Resolve to relink the cut to those originals.
+
+Three Resolve-native mechanisms look like they will do this. All three were
+measured against one real 83-minute turnover (878 events, 882 timeline items,
+multi-layer, consolidated media) on Resolve 19.1.3. **All three fail, and the one
+that looks most convincing fails worst.**
+
+This guide is about Resolve's own behaviour. It is reproducible by anyone with an
+Avid AAF and a folder of camera originals.
+
+## The short answer
+
+| mechanism | what it does | verdict |
+| --- | --- | --- |
+| API `ImportTimelineFromFile` | `importSourceClips: true` creates **no timeline** at all. `importSourceClips: false` creates 882 items with **zero** media-pool items | unusable as a conform |
+| **Reconform from Bins** (timecode-only) | **678 / 882 linked** — and the links are the **wrong takes** | silently wrong |
+| **UI Import AAF + "Link to source camera files"** | **878 / 882 linked, only 144 correct — 734 wrong takes (84%)** | 🚨 **dangerous** |
+
+The camera-file link is the option whose name promises exactly what you want. It
+is the one to avoid.
+
+## Why the camera-file link is the dangerous option
+
+It links almost everything — 878 of 882 items — and **84% of those links are the
+wrong take.** Four consecutive cuts pointed at the same wrong file. A head slate
+linked to unrelated archival footage.
+
+And then it **renders as a fully conformed timeline.** There is no offline media,
+no red frames, no error, no warning. Every signal a conform is normally checked
+against says the job is done. You have to compare against a picture reference,
+frame by frame, to discover that most of the cut is showing the wrong moment.
+
+A conform that is 16% correct and looks 100% correct is worse than one that
+obviously fails, because the failure survives review.
+
+## Why the matching goes wrong
+
+Two reasons, and neither is a bug you can configure away.
+
+**Name matching is impossible.** A consolidated Avid turnover names its clips
+with instance names like `<something>.new.01` — names that belong to Avid's own
+media database and match no file on disk. There is nothing to match on.
+
+**Timecode alone is ambiguous.** Fall back to timecode and you get adjacent-take
+drift: the matcher lands on a *neighbouring take from the same roll* — one
+camera-roll index away from the right one. Those takes were often shot minutes
+apart, overlap in timecode, and are visually similar enough to pass a glance.
+That is the shape of the 678 Reconform-from-Bins links and the 734 wrong
+camera-file links alike.
+
+Adjacent takes are the worst possible failure mode: close enough to look
+plausible, wrong enough to be unusable.
+
+## What to do instead
+
+**Conform against the consolidated media the AAF actually references, not against
+camera originals.** The AAF's source references describe the consolidated
+fragments; those match. Relinking to camera originals is a *second*, separate
+problem — one that needs the source position and source timecode of each event,
+not just its take name.
+
+If you must reach the camera originals, you need per-event evidence beyond the
+AAF's own clip names:
+
+- the **physical source position and timecode** of each cut (`aaf_probe.py` emits
+  `srcPos`, `srcTcFrame`, `srcTc`, `srcTcFps`, `srcTcDrop` per event — a
+  fragment-relative source offset is not a position in the take, which is its own
+  well-documented trap);
+- the sequence **start timecode** (`startTimecode` / `startFrame`), because a cut
+  built at Resolve's 01:00:00:00 default when the AAF starts at 00:59:50:00 is ten
+  seconds out everywhere and only visible against a linked reference;
+- an independent **picture reference** to verify against.
+
+**Verify against a reference, always.** Whatever route you take, the only witness
+that catches adjacent-take drift is a frame comparison against a reference render
+or picture reference. Item counts, "linked" counts, and the absence of offline
+media all agree with a conform that is 84% wrong. A witness derived from the same
+state as the thing it is checking cannot contradict it.
+
+## Related
+
+- `docs/reference/api-limitations.md` — the scripting-API entries behind this,
+  including `MediaPool.ImportTimelineFromFile` and the `AppendToTimeline`
+  placement and durability limits you will hit if you build the timeline
+  yourself.
+- `docs/guides/headless-edit-loop.md` — which interchange formats relink at all
+  when media has moved (DRT, OTIO and EDL do not).
+</content>

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 25 missing capabilities, 25 bugs / unreliable behaviors.
+**Totals:** 25 missing capabilities, 28 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -117,9 +117,9 @@ equivalent, blocking full automation.
 ### Clip speed / retime ratio and speed ramps
 
 - **Object:** `TimelineItem`
-- **Behavior:** SetProperty exposes only retime *quality* (RetimeProcess, MotionEstimation) and transform/crop/composite/opacity keys — not the speed value itself. There is no way to set a clip to a given % speed, reverse it, or author a speed ramp. Verified against the documented SetProperty key list AND by live mutating attempt on 21.0.0: SetProperty('Speed'|'PlaybackSpeed'|'RetimeSpeed'|'ClipSpeed', 50) all return False, while SetProperty('RetimeProcess', 1) returns True.
-- **Workaround / current handling:** Set clip speed/retime in the Resolve UI; no scripted equivalent exists.
-- **Tags:** missing-method, timeline, retime, speed
+- **Behavior:** SetProperty exposes only retime *quality* (RetimeProcess, MotionEstimation) and transform/crop/composite/opacity keys — not the speed value itself. There is no way to set a clip to a given % speed, reverse it, or author a speed ramp. Verified against the documented SetProperty key list AND by live mutating attempt on 21.0.0: SetProperty('Speed'|'PlaybackSpeed'|'RetimeSpeed'|'ClipSpeed', 50) all return False, while SetProperty('RetimeProcess', 1) returns True. THE READ SIDE IS AS DEAD AS THE WRITE SIDE, which is easy to miss: re-measured on Studio 19.1.3.7 against a placed item, GetProperty('Speed'), GetProperty('PlaybackSpeed'), GetProperty('RetimeSpeed') and GetProperty('ClipSpeed') ALL return None, and the keyless GetProperty() dict (26 keys on that item) carries no speed value at all — its only retime key is RetimeProcess, which is quality, not ratio. SetProperty('Speed', 1.75) returned False on 19.1.3.7 too, so the write refusal is not specific to 21.0.0. Note the 21.0.0 stamp above covers the SetProperty measurements only. THE INTERCHANGE ROUTE IS ALSO CLOSED — carrying a retime in through FCP7 XML does not work either, measured on 19.1.3 with three real files, clips at 100/200/50% on V1, each variant imported as its own timeline: (a) the importer IGNORES the scalar Time Remap speed filter and the clips arrive at 100%; (b) `graphdict` is dead in FOUR separate shapes — the full Premiere form (variablespeed=0 + speed + reverse=FALSE + frameblending + 4-keyframe graphdict + FCPCurve), graphdict alone with no <speed> param, a 100% REVERSE (reverse=TRUE plus a descending graphdict, the exact shape a real Premiere export carries), and variablespeed=1 + graphdict — 0 of 2 retimes landed in every one; (c) `reverse` did not survive either; (d) any <in>/<pproTicksIn> inconsistency is silently REJECTED, measured in BOTH orientations. The emitted maps were verified constant-slope against real Premiere exports before importing, and every imported clip came back consuming exactly its record span of source (a 200% clip emitted in 200 / out 296 was clamped to out 248 — 48 source frames over a 48-frame record span). Placement is NOT the problem: the same route imported 573 clips with 572 of 573 matching by track and record position with source frames exact, and the importer BUILT a 59-frame dissolve. The retime gap is specific, not general. TRAP: Resolve's own FCP7 export cannot witness a speed. It writes a DEGENERATE Time Remap on every clip — `speed` value 0 (not 100) and a graphdict whose keyframe `value`s are all 0 while its `when`s carry the clip's source in/out — so anyone verifying a retime by round-tripping through EXPORT_FCP_7_XML is reading furniture, and the identity Time Remap blocks present on every clip are what make the route look like it should work.
+- **Workaround / current handling:** Set clip speed/retime in the Resolve UI; no scripted equivalent exists, and no interchange route carries one in. Do NOT read speed back with GetProperty (None) or witness it via EXPORT_FCP_7_XML (degenerate). Read the clip's GEOMETRY instead — GetLeftOffset / GetRightOffset, which on the 200% clip read 200 / 248 and agreed with the export's in/out. Caveat worth stating: no positive control has been run — no clip KNOWN to be retimed has been read back through those two witnesses, because there is no scripting path to create one. So the geometry witness is the best available, not a proven one. Either way the interchange route is rejected: no retime was built, and none could have been verified.
+- **Tags:** missing-method, timeline, retime, speed, interchange, silent-failure, unreliable-return
 
 ### Color node graph editing and primary grade values
 
@@ -281,7 +281,7 @@ values, or automation-hostile modal prompts.
 - **Object:** `MediaPool`
 - **Signature:** `(filePath, {importOptions}) -> Timeline`
 - **Behavior:** Returns None — no error, no exception — when the requested `timelineName` already exists. Measured: importing one file three times with the same name succeeded once and returned None twice. An iterative loop that reuses a fixed name therefore works exactly once and then silently does nothing. DRT ignores importOptions entirely (timelineName, importSourceClips and sourceClipsFolders are all invalid for it): the timeline is named after the FILE, repeats auto-uniquify ('iter', 'iter 2', 'iter 3'), and because importSourceClips cannot be disabled each DRT import adds another copy of the source media to the pool. OTIO is the one format that will NOT relink from the pool — with importSourceClips=False its timeline rebuilds with correct structure and every item OFFLINE, in both GUI and headless.
-- **Workaround / current handling:** For a repeatable loop use FCP7 XML or AAF with a UNIQUE timelineName per iteration plus importSourceClips=False and sourceClipsFolders=[root] — verified frame-exact over five consecutive imports with no media duplicated. Use DRT for one-shot hand-offs only. For OTIO, pass importSourceClips=True with a sourceClipsPath. See docs/guides/headless-edit-loop.md.
+- **Workaround / current handling:** For a repeatable loop use FCP7 XML or AAF with a UNIQUE timelineName per iteration plus importSourceClips=False and sourceClipsFolders=[root] — verified frame-exact over five consecutive imports with no media duplicated. Use DRT for one-shot hand-offs only. For OTIO, pass importSourceClips=True with a sourceClipsPath. See docs/guides/headless-edit-loop.md. For a consolidated Avid AAF specifically, do NOT expect this call (or Reconform from Bins, or the UI's 'Link to source camera files') to conform it to camera originals — all three were measured against a real turnover and all three fail, the UI option linking 878 of 882 items with only 144 correct while rendering as a fully conformed timeline. See docs/guides/conforming-an-avid-aaf.md.
 - **Tags:** timeline, import, interchange, silent-failure, conform
 
 ### Timeline.Export(EXPORT_FCPXML_1_10)
@@ -295,9 +295,33 @@ values, or automation-hostile modal prompts.
 ### MediaPool.CreateTimelineFromClips
 
 - **Object:** `MediaPool`
-- **Behavior:** Fails with a bare 'Failed to create timeline from clip_infos' — naming nothing actionable — when the Media Pool's CURRENT folder is not the folder holding the clips, even though every clip_id passed is valid and resolvable. Reported against Resolve Studio in PR #99.
-- **Workaround / current handling:** Call MediaPool.SetCurrentFolder() to the clips' bin before creating the timeline (media_pool set_current_folder). Valid ids are not sufficient.
-- **Tags:** media-pool, timeline, unhelpful-error
+- **Behavior:** Fails with a bare 'Failed to create timeline from clip_infos' — naming nothing actionable — when the Media Pool's CURRENT folder is not the folder holding the clips, even though every clip_id passed is valid and resolvable. Reported against Resolve Studio in PR #99. SEPARATELY, its clipInfo HAS NO TRACK FIELD: there is no way to say which video or audio track a clip should land on, so this call cannot build a multi-track timeline. The asymmetry is the surprise — MediaPool.AppendToTimeline's clipInfo DOES take `trackIndex`, so the two clipInfo shapes are not the same shape, and code that works against one silently loses track assignment against the other.
+- **Workaround / current handling:** Call MediaPool.SetCurrentFolder() to the clips' bin before creating the timeline (media_pool set_current_folder). Valid ids are not sufficient. For multi-track placement do not use this call at all: create an EMPTY timeline (media_pool create_timeline), add the tracks you need (timeline add_track), then place each clip with MediaPool.AppendToTimeline passing clipInfo `trackIndex` (media_pool append_to_timeline with track_index).
+- **Tags:** media-pool, timeline, unhelpful-error, missing-method, conform
+
+### MediaPool.AppendToTimeline (overlapping records — earlier item wins)
+
+- **Object:** `MediaPool`
+- **Signature:** `([{mediaPoolItem, startFrame, endFrame, recordFrame, trackIndex, mediaType}]) -> [TimelineItem]`
+- **Behavior:** AppendToTimeline does NOT overwrite an overlapping record. When two clipInfos resolve to record ranges that overlap on the same track, the EARLIER item wins and the later append is dropped — measured while placing a real turnover. There is no overwrite edit mode to reach for either: AppendToTimeline is the only programmatic placement the API offers, so a consumer that assumes overwrite semantics gets a timeline that is silently SHORT by the number of colliding events, with no error to say which ones lost.
+- **Workaround / current handling:** Resolve collisions BEFORE appending — the API will not do it for you. Cap each event's placed duration at the next event's recordFrame on the same track, or place the colliding events on separate tracks. Verify by comparing the timeline's item count against the number of clipInfos you sent, per track, and finish with detect_gaps_overlaps; a count that matches is the only evidence nothing was dropped.
+- **Tags:** timeline, edit, silent-failure, conform, media-pool
+
+### MediaPool.AppendToTimeline (errored-chunk placements are not durable across a save)
+
+- **Object:** `MediaPool`
+- **Signature:** `([clipInfos]) -> [TimelineItem]`
+- **Behavior:** Placements made by an append call whose response ERRORED are not durable: they appear in the timeline, every in-session read agrees they are there, and THE SAVE DISCARDS THEM. Measured on a real turnover — a timeline verified at 573 items immediately after construction held 500 after the save, a loss of exactly one errored append chunk's worth. The API reported the failure, the items appeared anyway, and nothing between construction and the save disagreed with the wrong number. This is the dangerous shape: the witness is derived from the same unsaved state as the thing it is checking, so it cannot contradict it. Only a POST-SAVE read can.
+- **Workaround / current handling:** Treat the save as the verification boundary, not the end of the job. Save, RE-READ the timeline's item count from the saved project, and re-append whatever is missing (bounded — two rounds is enough in practice); only then report success. A timeline that is still short after that, or that will not save, is a FAILURE — report it as one rather than returning the in-session count. Never claim a construction succeeded on a pre-save read alone, and treat any errored append chunk as suspect even when its items are visibly present.
+- **Tags:** timeline, edit, silent-failure, data-loss, conform, unreliable-return, media-pool
+
+### MediaPool.ImportTimelineFromFile (.otio document shape)
+
+- **Object:** `MediaPool`
+- **Signature:** `(filePath, {importOptions}) -> Timeline`
+- **Behavior:** Resolve DOES import OTIO through the scripting API — but only a Resolve-shaped document, and it rejects anything else by creating NO timeline and returning None, with no error naming a cause. Established on 19.1.3.7 by exporting a timeline with Timeline.Export(..., EXPORT_OTIO) and feeding Resolve's own file straight back: it re-imports cleanly (3 items, 3 linked), while a valid hand-authored OTIO of the same cut, same project, same session, same three online media files, produced nothing. So a refusal is a SHAPE problem, not a media problem. The requirement that actually decides it is the SOURCE FRAME ORIGIN: a clip's source_range must be expressed against the media's own timecode range. Media carrying an embedded start TC of 01:00:00:00 gets an available_range starting at frame 86400, and the clip's source_range must start there too — 0-based source offsets, the natural reading of 'source in point', put the clip outside the media's real range and the import dies. Isolated by bisection: 0-based fails and absolute succeeds whether or not the stack/track source_range is null. Resolve also writes (and expects) Clip.2 with a `media_references` MAP plus `active_media_reference_key`, not Clip.1 with a singular `media_reference`; an `available_range` on each reference; a BARE path in `target_url`, not a file:// URL; `enabled` and `metadata` throughout; `global_start_time`; and track names in its own form ('Video 1').
+- **Workaround / current handling:** Author OTIO for Resolve by mirroring what Resolve itself exports, and give every event its media timecode origin. editorial.convert_to_interchange (target 'otio') does this and reports any event whose origin had to be assumed in `mediaOriginAssumed` — a non-empty list means the file will only import if that media really starts at 00:00:00:00. To debug a refusal, export any timeline with EXPORT_OTIO and diff your document against it; do NOT chase missing media or reach for sanitize_media, which cannot even parse a .otio (it is JSON, not XML).
+- **Tags:** timeline, import, interchange, otio, silent-failure, conform
 
 ### TimelineItem.AddFusionComp / LoadFusionCompByName
 
@@ -374,13 +398,17 @@ 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)
+### Timeline.DeleteClips (requires the Edit page; 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
+- **Behavior:** Two distinct failures share this call.
+
+  **1. Wrong page (deterministic, has a mechanism).** With the UI on the Fairlight page, DeleteClips returns False and deletes nothing, no matter how many times it is retried. Verified 2026-08-04 on Studio 21.0: three identical retries against 132 valid, unlocked, present TimelineItems all returned False with all 132 still on the track; a single `Resolve.OpenPage("edit")` followed by the same call returned True and left 0 items. Track lock and enable state were confirmed clear before and after, so this is a page gate, not a lock. This is the case the previous entry's falsification condition anticipated — a retry seen to fail repeatedly — and revisiting it found the mechanism.
+
+  **2. Flaky first attempt (one observation, no mechanism).** Independently of the page, the call has been seen once to return False with every item still present, where an identical immediate retry succeeded (Studio 21.0, cut-video edit session). Whether the UI was on the Edit page at the time was not recorded, so it cannot be ruled in or out as failure 1 in disguise. 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. One observation is still not a mechanism; if an immediate retry is ever seen to fail repeatedly while the UI is confirmed on the Edit page, this sub-entry needs revisiting.
+- **Workaround / current handling:** Open the Edit page first (`Resolve.OpenPage("edit")`) — a caller that deletes clips from a script must not assume the user left the UI on Edit, and a Fairlight or Color session is a completely ordinary place for them to be. Then 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, silent-failure, page-dependent, timeline, edit
 
 ### MediaPool.AppendToTimeline with mixed-fps sources (duration floor)
 

package/install.py

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

package/package.json

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

package/resolve-advanced/README.md

@@ -98,7 +98,9 @@ Each dispatches on an `action`. Highlights:
   **.prproj via gunzip+XML** — pass the file PATH for the binary ones), `list_sequences` (one picker entry
   point across xml/edl/otio/drt/drp/aaf/prproj), `convert_to_interchange` (author OTIO/EDL/DRT that Resolve
   imports, from events or a parsed source — **the .prproj→Resolve conform bridge**, no Premiere needed;
-  editorial timing/cuts/transitions/speed carry, per-clip effects/color do not),
+  editorial timing/cuts/transitions carry, per-clip effects/color do not; speed/reverse carry on
+  the `otio` and `edl` targets only — `drt` has no per-clip speed field and reports every retime it
+  flattens in `flattened`),
   `turnover_changelist` (moved/retimed/replaced/new/gone + timing silent-lie guards), `conform_manifest`,
   `marker_roundtrip`.
 - **`provenance`** — provenance / audit: `gallery_lineage`, `grade_provenance` ("why is this graded this

package/resolve-advanced/server/author-interchange.mjs

@@ -28,12 +28,71 @@ const byTrack = (events) => {
   return groups;
 };
 
+/**
+ * Events whose media timecode ORIGIN had to be assumed as 0 when authoring OTIO. Resolve
+ * measures a clip's source_range against the media's real timecode range, so an event with
+ * no origin only imports if its media genuinely starts at 00:00:00:00 — otherwise the file
+ * looks fine and Resolve creates no timeline. Supply `mediaStartTcFrame` (or an absolute
+ * `srcTcFrame`) per event to clear it. Always an array, empty when every event carried one.
+ */
+export function otioMediaOriginAssumed(events) {
+  const out = [];
+  (events || []).forEach((e, index) => {
+    if (e.srcTcFrame != null || e.mediaStartTcFrame != null || e.startTcFrame != null) return;
+    out.push({
+      index,
+      recIn: e.recIn ?? 0,
+      srcIn: e.srcIn ?? 0,
+      source: e.source || '',
+      reason: 'no media timecode origin — assumed 00:00:00:00; Resolve rejects the import if the media starts elsewhere',
+    });
+  });
+  return out;
+}
+
+const rt = (value, rate) => ({ OTIO_SCHEMA: 'RationalTime.1', rate: Number(rate), value: Number(value) });
+const tr = (start, duration, rate) => ({ OTIO_SCHEMA: 'TimeRange.1', duration: rt(duration, rate), start_time: rt(start, rate) });
+const basename = (p) => String(p || '').split('/').pop() || 'UNKNOWN';
+
 /**
  * Build an OTIO timeline doc (plain object) from normalized events. Inserts gaps so record
  * positions are exact; emits LinearTimeWarp for speed/reverse and Transition items where present.
+ *
+ * The emitted shape mirrors what Resolve's own EXPORT_OTIO writes, because Resolve's importer
+ * is far pickier than the OTIO spec. Measured on 19.1.3: a Resolve-authored .otio re-imports
+ * through MediaPool.ImportTimelineFromFile (3 items, 3 linked) while the shape this function
+ * used to emit produced NO TIMELINE — same project, same session, same three online media
+ * files. So the scripting API imports OTIO fine; what it rejects is a document that is valid
+ * OTIO but not Resolve-shaped. The parts that matter:
+ *
+ *   - `Clip.2` with a `media_references` MAP + `active_media_reference_key`, not `Clip.1`
+ *     with a singular `media_reference`. This is the one that most looks like a free choice
+ *     and is not.
+ *   - `available_range` on the external reference, and a clip `name` that is the media
+ *     BASENAME rather than its full path.
+ *   - SOURCE FRAMES ARE TIMECODE-ABSOLUTE. This is the one that decides the import. The
+ *     media used to measure this carries an embedded start TC of 01:00:00:00, so Resolve
+ *     writes its `available_range` starting at frame 86400 and the clip's `source_range`
+ *     at 86400 too. Emitting the same cut with 0-based source offsets — the natural
+ *     reading of "source in point" — produced NO TIMELINE, because frame 0 is outside the
+ *     media's real range. Bisected: 0-based fails and absolute succeeds whether or not the
+ *     stack/track `source_range` is null, so it is the frame origin that matters and not
+ *     the surrounding shape. Same lesson as srcIn being fragment-relative on consolidated
+ *     media: a source position means nothing without the origin it is measured from.
+ *   - `enabled: true` on stack, tracks and clips; `metadata` objects present (Resolve stamps
+ *     its own `Resolve_OTIO` block and reads the tracks' back).
+ *   - `global_start_time` on the timeline, and track names in Resolve's own form ("Video 1").
+ *
+ * Give the media's TC origin per event as `mediaStartTcFrame` (or an already-absolute
+ * `srcTcFrame`). Without it this falls back to a 0 origin, which only imports when the media
+ * really does start at 00:00:00:00 — so the events that had to be assumed are reported back
+ * in `mediaOriginAssumed` rather than silently producing a file that imports as nothing.
+ *
+ * Handy inverse: this repo's parseOTIO still reads what we emit, so the bridge round-trips.
  */
 export function eventsToOTIO(events, opts = {}) {
   const fps = opts.fps || events.find((e) => e.fps)?.fps || 24;
+  const startFrame = opts.startFrame ?? opts.globalStartFrame ?? 0;
   const groups = byTrack(events);
   const tracks = [];
   for (const [kind, list] of [
@@ -48,40 +107,88 @@ export function eventsToOTIO(events, opts = {}) {
       if (recIn > rec) {
         children.push({
           OTIO_SCHEMA: 'Gap.1',
-          source_range: { OTIO_SCHEMA: 'TimeRange.1', duration: { OTIO_SCHEMA: 'RationalTime.1', value: recIn - rec, rate: fps } },
+          metadata: {},
+          source_range: { OTIO_SCHEMA: 'TimeRange.1', duration: rt(recIn - rec, fps), start_time: rt(0, fps) },
+          effects: [],
+          markers: [],
+          enabled: true,
         });
         rec = recIn;
       }
       const recDur = (e.recOut ?? recIn) - recIn;
+      const clipFps = e.fps || fps;
+      const srcIn = e.srcIn ?? 0;
+      // The media's timecode origin. srcTcFrame (already absolute) wins; otherwise the
+      // media start TC plus the in-point. A 0 origin is an ASSUMPTION, and it is recorded.
+      const mediaStart = e.mediaStartTcFrame ?? e.startTcFrame ?? null;
+      const srcStart = e.srcTcFrame ?? (mediaStart ?? 0) + srcIn;
+      const availStart = e.srcTcFrame != null ? e.srcTcFrame - srcIn : (mediaStart ?? 0);
       const clip = {
-        OTIO_SCHEMA: 'Clip.1',
-        name: e.source || 'UNKNOWN',
-        source_range: {
-          OTIO_SCHEMA: 'TimeRange.1',
-          start_time: { OTIO_SCHEMA: 'RationalTime.1', value: e.srcIn ?? 0, rate: e.fps || fps },
-          duration: { OTIO_SCHEMA: 'RationalTime.1', value: recDur, rate: e.fps || fps },
-        },
-        media_reference: { OTIO_SCHEMA: 'ExternalReference.1', target_url: e.source || '' },
+        OTIO_SCHEMA: 'Clip.2',
+        metadata: {},
+        name: basename(e.source),
+        source_range: tr(srcStart, recDur, clipFps),
         effects: [],
         markers: [],
+        enabled: true,
+        media_references: {
+          DEFAULT_MEDIA: {
+            OTIO_SCHEMA: 'ExternalReference.1',
+            metadata: {},
+            name: basename(e.source),
+            // Resolve writes a BARE path here, not a file:// URL.
+            target_url: e.source || '',
+            available_range: tr(availStart, e.mediaDuration ?? e.srcAvailDuration ?? Math.max(recDur, srcIn + recDur), clipFps),
+            available_image_bounds: null,
+          },
+        },
+        active_media_reference_key: 'DEFAULT_MEDIA',
       };
       if ((e.speed ?? 100) !== 100 || e.reverse) {
-        clip.effects.push({ OTIO_SCHEMA: 'LinearTimeWarp.1', name: 'Speed', time_scalar: (e.reverse ? -1 : 1) * ((e.speed ?? 100) / 100) });
+        clip.effects.push({ OTIO_SCHEMA: 'LinearTimeWarp.1', name: 'Speed', metadata: {}, effect_name: 'LinearTimeWarp', time_scalar: (e.reverse ? -1 : 1) * ((e.speed ?? 100) / 100) });
       }
       if (e.transition) {
         children.push({
           OTIO_SCHEMA: 'Transition.1',
+          metadata: {},
+          name: 'Cross Dissolve',
           transition_type: 'SMPTE_Dissolve',
-          in_offset: { OTIO_SCHEMA: 'RationalTime.1', value: Math.ceil((e.transition.duration || 0) / 2), rate: fps },
-          out_offset: { OTIO_SCHEMA: 'RationalTime.1', value: Math.floor((e.transition.duration || 0) / 2), rate: fps },
+          in_offset: rt(Math.ceil((e.transition.duration || 0) / 2), fps),
+          out_offset: rt(Math.floor((e.transition.duration || 0) / 2), fps),
         });
       }
       children.push(clip);
       rec = recIn + recDur;
     }
-    tracks.push({ OTIO_SCHEMA: 'Track.1', name: `${kind[0]}1`, kind, children });
+    tracks.push({
+      OTIO_SCHEMA: 'Track.1',
+      metadata: {},
+      name: `${kind} 1`,
+      source_range: tr(0, rec, fps),
+      effects: [],
+      markers: [],
+      enabled: true,
+      children,
+      kind,
+    });
   }
-  return { OTIO_SCHEMA: 'Timeline.1', name: opts.name || 'Conformed', tracks: { OTIO_SCHEMA: 'Stack.1', name: 'tracks', children: tracks } };
+  const stackDur = tracks.reduce((m, t) => Math.max(m, t.source_range.duration.value), 0);
+  return {
+    OTIO_SCHEMA: 'Timeline.1',
+    metadata: {},
+    name: opts.name || 'Conformed',
+    global_start_time: rt(startFrame, fps),
+    tracks: {
+      OTIO_SCHEMA: 'Stack.1',
+      metadata: {},
+      name: 'tracks',
+      source_range: tr(0, stackDur, fps),
+      effects: [],
+      markers: [],
+      enabled: true,
+      children: tracks,
+    },
+  };
 }
 
 /** Build a CMX3600 EDL string (cuts + M2 speed). Video events only, per EDL convention. */
@@ -108,6 +215,35 @@ export function eventsToEDL(events, opts = {}) {
   return lines.join('\n') + '\n';
 }
 
+const isRetimed = (e) => (e.speed ?? 100) !== 100 || Boolean(e.reverse);
+
+/**
+ * Which events lose their retime on the DRT target. The DRT clip schema
+ * (vendor/drp-format/seq-container-builder.js) carries start / duration / in /
+ * mediaFilePath / mediaStartTime / mediaFrameRate and nothing else — there is no per-clip
+ * speed field to write a retime into, so a retimed event lands at 100% forward. OTIO
+ * (LinearTimeWarp) and EDL (M2) do carry it; only DRT flattens.
+ *
+ * Reporting it is this cluster's skip-not-fake contract: a flattened retime that nobody is
+ * told about is a timeline the caller believes is conformed and is not. `index` is the
+ * event's position in the ORIGINAL events array, so a caller can map straight back.
+ */
+export function drtFlattenedRetimes(events) {
+  const out = [];
+  (events || []).forEach((e, index) => {
+    if (!isRetimed(e)) return;
+    out.push({
+      index,
+      recIn: e.recIn ?? 0,
+      speed: e.speed ?? 100,
+      reverse: Boolean(e.reverse),
+      source: e.source || '',
+      reason: 'DRT clip schema has no per-clip speed field — retime flattened to 100% forward',
+    });
+  });
+  return out;
+}
+
 /** Build a buildDRT spec (Resolve-native .drt) from normalized events. */
 export function eventsToDrtSpec(events, opts = {}) {
   const fps = opts.fps || events.find((e) => e.fps)?.fps || 24;
@@ -133,12 +269,14 @@ export function eventsToDrtSpec(events, opts = {}) {
 /**
  * Author `events` into `target` interchange. Returns { target, content?, spec?, bytes? }.
  * For 'drt', when outputPath is given the .drt bytes are written; otherwise the spec is returned.
+ * The 'drt' target additionally returns `flattened` — ALWAYS an array, empty when the cut
+ * carries no retimes, so a caller can tell "none to lose" from "this build is too old to say".
  */
 export async function authorInterchange(events, target, opts = {}) {
   const t = String(target || 'otio').toLowerCase();
   if (t === 'otio') {
     const doc = eventsToOTIO(events, opts);
-    return { target: 'otio', content: JSON.stringify(doc, null, 2), doc };
+    return { target: 'otio', content: JSON.stringify(doc, null, 2), doc, mediaOriginAssumed: otioMediaOriginAssumed(events) };
   }
   if (t === 'edl') {
     return { target: 'edl', content: eventsToEDL(events, opts) };
@@ -146,7 +284,7 @@ export async function authorInterchange(events, target, opts = {}) {
   if (t === 'drt') {
     const spec = eventsToDrtSpec(events, opts);
     const buf = await drt().buildDRT(spec);
-    return { target: 'drt', spec, buffer: buf, bytes: buf.length };
+    return { target: 'drt', spec, buffer: buf, bytes: buf.length, flattened: drtFlattenedRetimes(events) };
   }
   throw new Error(`authorInterchange: unknown target '${target}' (otio|edl|drt)`);
 }

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

@@ -82,7 +82,7 @@ const markerSchema = z.object({
 export const editorialTool = {
   name: 'editorial',
   description:
-    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively + AAF via pyaaf2 + PRPROJ via gunzip+XML → normalized events; for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions/speed survive, per-clip effects/color do not), turnover_changelist (diff old vs new → moved/retimed/replaced/new/gone + timing flags), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base), marker_roundtrip (markers with provenance tags). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
+    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively + AAF via pyaaf2 + PRPROJ via gunzip+XML → normalized events; for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — the DRT clip schema has no per-clip speed field, so target `drt` flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one; `flattened` is always present on `drt`, empty when there were none), turnover_changelist (diff old vs new → moved/retimed/replaced/new/gone + timing flags), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base), marker_roundtrip (markers with provenance tags). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
   async handler({ action, args }) {
     if (action === 'parse_interchange') {
       const p = parseSchema.parse(args);
@@ -125,6 +125,10 @@ export const editorialTool = {
         eventCount: events.length,
         ...(written || { content: authored.content }),
         ...(authored.spec ? { spec: authored.spec } : {}),
+        // skip-not-fake: the DRT clip schema has no per-clip speed field, so retimes cannot
+        // ride into a .drt. Name every event that lost one rather than returning a timeline
+        // the caller believes is conformed. Always present on 'drt' (empty = none to lose).
+        ...(authored.flattened ? { flattened: authored.flattened, flattenedCount: authored.flattened.length } : {}),
       };
     }
     if (action === 'turnover_changelist') {