davinci-resolve-mcp 2.78.1 → 2.79.0

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",
     },
     {