davinci-resolve-mcp 2.78.1 → 2.79.1

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.78.1"
+VERSION = "2.79.1"
 
 import base64
 import os
@@ -5999,7 +5999,10 @@ _PRPROJ_REFUSAL = (
     "advanced MCP — editorial.list_sequences / editorial.parse_interchange (format 'prproj'); "
     "(2) convert it to an importable interchange — editorial.convert_to_interchange "
     "(target 'otio'|'edl'|'drt') — then import that here with import_timeline_checked. "
-    "Editorial timing/cuts/transitions/speed carry over; per-clip effects/Lumetri color do not. "
+    "Editorial timing/cuts/transitions carry over; per-clip effects/Lumetri color do not. "
+    "Speed/reverse carry on 'otio' and 'edl' ONLY — the DRT clip schema has no per-clip "
+    "speed field, so 'drt' flattens every retime to 100% forward and reports them in "
+    "`flattened`. Prefer 'otio' or 'edl' for a cut that carries retimes. "
     "Alternatively export FCP7 XML / AAF / FCPXML from Premiere and conform that."
 )
 
@@ -6008,6 +6011,12 @@ _PRPROJ_REFUSAL = (
 # pool after import, not by rewriting the file.
 _BINARY_INTERCHANGE_EXTS = {".aaf"}
 
+# Interchange that is not XML at all. `.otio` is JSON, so the sanitize/relink pass —
+# which parses the file as XML and rewrites <pathurl> elements — cannot run on it, and
+# the missing-media / generator-clip advice it exists to give is not the diagnosis for
+# an .otio that fails to import.
+_JSON_INTERCHANGE_EXTS = {".otio"}
+
 
 def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
     path = p.get("path")
@@ -6018,12 +6027,50 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
     ext = os.path.splitext(path)[1].lower()
     if ext == ".prproj":
         return _err(_PRPROJ_REFUSAL, category="invalid_input")
+    # ImportTimelineFromFile silently no-ops on the never-saved default project: it returns
+    # nothing, creates no timeline, and reports no cause. The generic "Resolve created no
+    # timeline" error that came back instead sent people to source-clip resolution and
+    # sanitize_media — the wrong road entirely, because the file is fine.
+    #
+    # This is the last unrecorded member of a family the repo already documents: SaveProject
+    # returns False here (and blocks forever headless), CreateProject fails against a dirty
+    # untitled project, and DeleteProject's workaround warns against leaving the session on
+    # this fallback. Refusing early is what makes the cause visible.
+    #
+    # The refusal is HARD — no override flag. An override would reintroduce exactly the
+    # silent no-op this exists to kill, since the call cannot succeed either way.
+    #
+    # Resolve exposes no "is this project unsaved" predicate (no IsModified / IsSaved), so
+    # the test is the literal fallback name. Known hole, stated rather than hidden: a
+    # localized Resolve may not name it "Untitled Project", and this guard will miss it —
+    # such a session gets the old generic error, not a wrong answer.
+    from src.utils.project_cleanup import UNSAVED_DEFAULT_PROJECT
+    try:
+        _current_name = proj.GetName()
+    except Exception:
+        _current_name = None
+    if _current_name == UNSAVED_DEFAULT_PROJECT:
+        return _err(
+            f"Cannot import a timeline into the never-saved default project "
+            f"('{UNSAVED_DEFAULT_PROJECT}') — Resolve accepts the call and creates no "
+            f"timeline, with no error naming the cause.",
+            category="invalid_input",
+            remediation=(
+                "The project state is the problem, not the file. Save this project under a "
+                "name, or load an existing named project (project_manager.load), then retry "
+                "the import unchanged."
+            ),
+        )
     # AAF (and any binary interchange) is read natively by Resolve. The XML
     # sanitize/relink path parses the file as text, so it must be SKIPPED for AAF
     # even when sanitize_media / relink_search_roots is passed; fuzzy XML relink is
     # N/A (media links through the media pool). We still detect the created
     # (possibly offline) timeline via the before/after id diff.
     is_binary = ext in _BINARY_INTERCHANGE_EXTS
+    # .otio is JSON. The sanitize/relink pass parses the file as XML, so it cannot run here
+    # any more than it can on an AAF — and its advice (missing media, generator clips) is
+    # not the diagnosis for an .otio that fails to import.
+    is_json = ext in _JSON_INTERCHANGE_EXTS
     # sanitize_media (alias: relink_media) rewrites the XML to drop clipitems that
     # reference missing media or are generators (slug/solid w/ no pathurl) — both
     # abort Resolve's scripting-API import and leave the timeline fully offline.
@@ -6043,7 +6090,13 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
             "relinks via the media pool. Imported the file as-is; pass relink_search_roots to "
             "auto-relink after import."
         )
-    sanitize = sanitize_requested and not is_binary
+    elif is_json and (sanitize_requested or _binary_has_roots):
+        binary_relink_note = (
+            f"sanitize_media / XML path-rewrite relink are N/A for {ext} (JSON, not XML) — "
+            "imported as-is. Media links by the target_url recorded in the file; relink via "
+            "the media pool afterward (see `relink`)."
+        )
+    sanitize = sanitize_requested and not is_binary and not is_json
     if not sanitize and p.get("require_temp_path", True) and not _render_temp_path_ok(path):
         return _err(
             "path must be under the system temp directory unless require_temp_path=False",
@@ -6140,6 +6193,26 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
                     "Otherwise verify it exports/opens in Resolve directly, or convert to "
                     "FCP7 XML / FCPXML upstream and import that."
                 )
+            elif is_json:
+                # Measured on 19.1.3: Resolve DOES import OTIO through the scripting API —
+                # its own EXPORT_OTIO output re-imports cleanly. What it refuses is a
+                # document that is valid OTIO but not Resolve-shaped, and the shape it cares
+                # about most is the source frame ORIGIN: a clip's source_range must sit
+                # inside the media's real timecode range, so 0-based source offsets against
+                # media that starts at 01:00:00:00 produce no timeline at all. Missing media
+                # and sanitize_media are not the diagnosis here and pointing at them wastes
+                # the caller's time on a file whose media is online.
+                remediation = (
+                    f"Resolve created no timeline from this {ext}. This is usually the "
+                    "document's shape, not its media: Resolve expects Clip.2 with a "
+                    "media_references map, an available_range on each reference, and "
+                    "source_range frames expressed against the media's own timecode origin "
+                    "(0-based source offsets fail when the media does not start at "
+                    "00:00:00:00). Author it with editorial.convert_to_interchange "
+                    "(target 'otio'), supplying each event's media start timecode, and check "
+                    "the returned mediaOriginAssumed list. To compare against a known-good "
+                    "file, export any timeline with timeline.export EXPORT_OTIO."
+                )
             elif sanitize:
                 remediation = None
             else:
@@ -6180,6 +6253,9 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
             if is_binary:
                 msg += (" Relink via the media pool (right-click → Relink Clips) or point Resolve "
                         "at the media roots — AAF media links there, not by rewriting the file.")
+            elif is_json:
+                msg += (" Relink via the media pool — .otio is JSON, so sanitize_media cannot "
+                        "rewrite its paths; check each clip's target_url instead.")
             elif not sanitize:
                 msg += (" Retry with sanitize_media=True to drop missing-media/generator "
                         "clips so the remaining media links automatically.")

package/src/utils/api_truth.py

@@ -181,7 +181,14 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "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.",
+                       "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"],
         "submit": "bug",
     },
@@ -274,11 +281,119 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "— 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.",
+                   "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.",
         "recommended": "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"],
+                       "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"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "MediaPool.AppendToTimeline (overlapping records — earlier item wins)",
+        "object": "MediaPool",
+        "signature": "([{mediaPoolItem, startFrame, endFrame, recordFrame, "
+                     "trackIndex, mediaType}]) -> [TimelineItem]",
+        "reality": "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.",
+        "recommended": "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"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "MediaPool.AppendToTimeline (errored-chunk placements are not durable across a save)",
+        "object": "MediaPool",
+        "signature": "([clipInfos]) -> [TimelineItem]",
+        "reality": "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.",
+        "recommended": "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"],
+        "submit": "bug",
+    },
+    {
+        "symbol": "MediaPool.ImportTimelineFromFile (.otio document shape)",
+        "object": "MediaPool",
+        "signature": "(filePath, {importOptions}) -> Timeline",
+        "reality": "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').",
+        "recommended": "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"],
         "submit": "bug",
     },
     {
@@ -554,10 +669,62 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "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.",
+                   "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.",
         "recommended": "Set clip speed/retime in the Resolve UI; no scripted "
-                       "equivalent exists.",
-        "tags": ["missing-method", "timeline", "retime", "speed"],
+                       "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"],
         "submit": "missing",
     },
     {