davinci-resolve-mcp 2.45.0 → 2.46.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 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.46.0
+
+Community PR bundle: five contributed fixes and features (#62–#66), live-validated
+on Resolve Studio 21.
+
+- **Fixed** timeline marker frames are now correctly relative to the timeline
+  start (#66): timecode params and the playhead default rebase by
+  `GetStartFrame()`, so markers on hour-start timelines land where the UI
+  shows them instead of an hour past the end. Raw `frame` params pass through
+  unchanged (documented as relative). Contact sheets and marker thumbnail
+  review rebase the other way with a legacy-absolute guard.
+- **Fixed** project lint no longer flags audio-only timelines as empty (#62);
+  live lint state now reports per-type `video/audio/subtitle_item_count`.
+- **Added** `media_pool.check_proxy_media_compatibility` (#63): ffprobe-vs-source
+  signature diagnostics (resolution/fps/frames/sample rate, expected
+  codec/profile). Same-aspect downscales count as compatible — half-res
+  proxies are the normal workflow.
+- **Added** readback verification envelopes (`verified_operation`) around
+  `media_pool.link_proxy_checked` (#63) and `media_pool.append_to_timeline`
+  (#64): preflight, execution, post-state readback, verification status, and a
+  journal event. `link_proxy_checked` gains `check_compatibility` /
+  `require_compatible` guards that refuse incompatible proxies before linking.
+- **Added** `bins` to declarative project specs (#65): missing media-pool bin
+  paths plan as `ensure` actions and are created idempotently; existing bins
+  are noops. Bin paths normalize to the `Master/` prefix so unprefixed spec
+  bins converge instead of reporting perpetual drift.
+
 ## What's New in v2.45.0
 
 The edit engine — Phase E, the final phase of the analysis + edit-engine

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.45.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.46.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)

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.45.0"
+VERSION = "2.46.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.45.0",
+  "version": "2.46.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.45.0"
+VERSION = "2.46.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/granular/timeline.py

@@ -461,7 +461,8 @@ def timeline_add_marker(frame_id: int, color: str, name: str, note: str = "", du
     """Add a marker to the current timeline.
 
     Args:
-        frame_id: Frame number for the marker.
+        frame_id: Frame number for the marker, relative to the timeline start
+            (frame 0 = first frame, even when the timeline starts at 01:00:00:00).
         color: Marker color (Blue, Cyan, Green, Yellow, Red, Pink, Purple, Fuchsia, Rose, Lavender, Sky, Mint, Lemon, Sand, Cocoa, Cream).
         name: Marker name.
         note: Marker note. Default: empty.

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.45.0"
+VERSION = "2.46.0"
 
 import base64
 import os
@@ -1347,6 +1347,46 @@ def _timeline_timecode_to_frame_id(tl, timecode):
     return _timecode_to_frame_id(timecode, fps)
 
 
+def _marker_rebase_to_timeline_start(tl, frame):
+    """Rebase an absolute frame to a Timeline marker frameId.
+
+    Timeline.AddMarker frameIds are relative to the timeline start (frame 0 ==
+    first frame of the timeline), while GetCurrentTimecode and the timecodes
+    shown in the Resolve UI are absolute. GetMarkers() echoes back whatever
+    frameId was passed without validating, so a marker stored at an absolute
+    frame displays past the end of the timeline (invisible in the UI).
+    Frames below the timeline start are treated as already relative (elapsed
+    time), and the frame passes through unchanged when the start frame is
+    unavailable.
+    """
+    start = _timeline_start_frame(tl)
+    if start and frame >= start:
+        return frame - start
+    return frame
+
+
+def _marker_timecode_to_frame_id(tl, timecode):
+    frame, err = _timeline_timecode_to_frame_id(tl, timecode)
+    if err:
+        return None, err
+    return _marker_rebase_to_timeline_start(tl, frame), None
+
+
+def _marker_display_frame(tl, frame):
+    """Absolute frame for driving the playhead at a stored marker frameId.
+
+    Inverse of _marker_rebase_to_timeline_start: stored timeline marker keys
+    are relative to the timeline start, while SetCurrentTimecode is absolute.
+    Frames at or past the start frame are assumed to be legacy absolute keys
+    and pass through unchanged so they still sample the intended frame.
+    """
+    frame = int(frame)
+    start = _timeline_start_frame(tl)
+    if start and frame < start:
+        return frame + start
+    return frame
+
+
 def _frame_id_to_timecode(frame: int, fps: float, separator: str = ":") -> str:
     nominal_fps = max(1, int(round(float(fps))))
     frame = max(0, int(frame))
@@ -1364,6 +1404,7 @@ def _timeline_frame_id_to_timecode(tl, frame: int) -> Tuple[Optional[str], Optio
 
 
 def _current_timeline_frame_id(tl):
+    """Absolute frame at the playhead, matching TimelineItem.GetStart()."""
     if tl is None:
         return None, _err("current playhead marker requires a timeline")
     try:
@@ -1375,23 +1416,37 @@ def _current_timeline_frame_id(tl):
     return _timeline_timecode_to_frame_id(tl, timecode)
 
 
+def _current_timeline_marker_frame_id(tl):
+    frame, err = _current_timeline_frame_id(tl)
+    if err:
+        return None, err
+    return _marker_rebase_to_timeline_start(tl, frame), None
+
+
 def _marker_frame_from_params(p: Dict[str, Any], tl=None, default_to_current=False):
+    """Resolve marker frame params to a marker frameId.
+
+    With a timeline, timecodes (and the playhead default) are rebased so the
+    returned frameId is relative to the timeline start. Raw frame numbers are
+    passed through unchanged: timeline marker frames are relative to the
+    timeline start, clip marker frames are relative to the clip start.
+    """
     raw_timecode = _first_param(p, "timecode", "time_code", "tc")
     if raw_timecode is not None:
-        return _timeline_timecode_to_frame_id(tl, raw_timecode)
+        return _marker_timecode_to_frame_id(tl, raw_timecode)
 
     raw_frame = _first_param(p, "frame", "frame_id", "frameId", "frame_num", "frameNum")
     if raw_frame is not None:
         if isinstance(raw_frame, str):
             lowered = raw_frame.strip().lower()
             if lowered in {"current", "playhead", "current_playhead", "now"}:
-                return _current_timeline_frame_id(tl)
+                return _current_timeline_marker_frame_id(tl)
             if ":" in raw_frame or ";" in raw_frame:
-                return _timeline_timecode_to_frame_id(tl, raw_frame)
+                return _marker_timecode_to_frame_id(tl, raw_frame)
         return _coerce_marker_number(raw_frame, "frame")
 
     if default_to_current:
-        return _current_timeline_frame_id(tl)
+        return _current_timeline_marker_frame_id(tl)
     return None, _err("Missing marker frame. Provide frame, frame_id/frameId, or timecode.")
 
 
@@ -4821,7 +4876,7 @@ def _timeline_thumbnail_contact_sheet(proj, tl, p: Dict[str, Any]) -> Dict[str,
     sampled = []
     try:
         for sample in samples:
-            timecode, tc_err = _timeline_frame_id_to_timecode(tl, int(sample["frame"]))
+            timecode, tc_err = _timeline_frame_id_to_timecode(tl, _marker_display_frame(tl, sample["frame"]))
             if tc_err:
                 sample["error"] = tc_err.get("error")
                 sampled.append(sample)
@@ -6139,6 +6194,7 @@ _MEDIA_POOL_KERNEL_ACTIONS = [
     "metadata_field_inventory",
     "safe_relink",
     "safe_unlink",
+    "check_proxy_media_compatibility",
     "link_proxy_checked",
     "link_full_resolution_checked",
     "set_clip_marks",
@@ -9474,7 +9530,8 @@ def _media_pool_ingest_capabilities():
                 "relink/unlink through Resolve MediaPool APIs",
                 "media_pool.safe_relink and safe_unlink with path/clip validation",
                 "proxy link/unlink through MediaPoolItem APIs",
-                "media_pool.link_proxy_checked with file validation",
+                "media_pool.check_proxy_media_compatibility with ffprobe/source signature diagnostics",
+                "media_pool.link_proxy_checked with file validation and optional compatibility guard",
                 "full-resolution media link where Resolve 20 exposes it",
                 "media_pool.link_full_resolution_checked with version/path validation",
             ],
@@ -9959,6 +10016,466 @@ def _safe_unlink(mp, root, p: Dict[str, Any]):
     return {"success": bool(mp.UnlinkClips(clips)), "count": len(clips), "missing": missing}
 
 
+def _parse_rate(value):
+    if value in (None, "", "0/0", "N/A"):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    text = str(value).strip()
+    if not text:
+        return None
+    if "/" in text:
+        left, right = text.split("/", 1)
+        try:
+            numerator = float(left.strip())
+            denominator = float(right.strip())
+            return numerator / denominator if denominator else None
+        except (TypeError, ValueError):
+            return None
+    match = re.search(r"\d+(?:\.\d+)?", text.replace(",", "."))
+    return float(match.group(0)) if match else None
+
+
+def _parse_int_text(value):
+    if value in (None, "", "N/A"):
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    match = re.search(r"\d+", str(value).replace(",", ""))
+    return int(match.group(0)) if match else None
+
+
+def _parse_resolution(value):
+    if value in (None, "", "N/A"):
+        return None
+    if isinstance(value, (list, tuple)) and len(value) >= 2:
+        width = _parse_int_text(value[0])
+        height = _parse_int_text(value[1])
+        return (width, height) if width and height else None
+    match = re.search(r"(\d+)\s*[xX]\s*(\d+)", str(value))
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2))
+
+
+def _normalize_media_token(value):
+    return re.sub(r"[^a-z0-9]+", "", str(value or "").lower())
+
+
+def _media_token_matches(actual, expected):
+    expected_token = _normalize_media_token(expected)
+    if not expected_token:
+        return True
+    actual_token = _normalize_media_token(actual)
+    return bool(actual_token) and (
+        actual_token == expected_token
+        or expected_token in actual_token
+        or actual_token in expected_token
+    )
+
+
+def _clip_media_signature(clip):
+    properties, properties_error = _safe_clip_call(clip, "GetClipProperty", "")
+    properties = properties if isinstance(properties, dict) else {}
+    resolution = _parse_resolution(
+        properties.get("Resolution")
+        or properties.get("Video Resolution")
+        or properties.get("Image Size")
+    )
+    signature = {
+        "name": _safe_media_pool_item_name(clip),
+        "id": _safe_media_pool_item_id(clip),
+        "file_path": properties.get("File Path") or properties.get("FilePath"),
+        "resolution": {"width": resolution[0], "height": resolution[1]} if resolution else None,
+        "fps": _parse_rate(
+            properties.get("FPS")
+            or properties.get("Frame Rate")
+            or properties.get("Video Frame Rate")
+        ),
+        "frames": _parse_int_text(
+            properties.get("Frames")
+            or properties.get("Frame Count")
+            or properties.get("Duration Frames")
+        ),
+        "sample_rate": _parse_int_text(
+            properties.get("Sample Rate")
+            or properties.get("Audio Sample Rate")
+        ),
+    }
+    if properties_error:
+        signature["properties_error"] = properties_error
+    return signature
+
+
+def _probe_media_file(path: str):
+    ffprobe = shutil.which("ffprobe")
+    if not ffprobe:
+        return {
+            "success": False,
+            "code": "FFPROBE_MISSING",
+            "error": "ffprobe is not installed or not on PATH",
+            "path": path,
+        }
+    try:
+        proc = subprocess.run(
+            [
+                ffprobe,
+                "-v",
+                "error",
+                "-show_streams",
+                "-of",
+                "json",
+                path,
+            ],
+            capture_output=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=20,
+            stdin=subprocess.DEVNULL,
+        )
+    except subprocess.TimeoutExpired:
+        return {"success": False, "code": "FFPROBE_TIMEOUT", "error": "ffprobe timed out", "path": path}
+    except Exception as exc:
+        return {"success": False, "code": "FFPROBE_FAILED", "error": str(exc), "path": path}
+    if proc.returncode != 0:
+        return {
+            "success": False,
+            "code": "FFPROBE_FAILED",
+            "returncode": proc.returncode,
+            "error": (proc.stderr or proc.stdout or "").strip(),
+            "path": path,
+        }
+    try:
+        payload = json.loads(proc.stdout or "{}")
+    except json.JSONDecodeError as exc:
+        return {"success": False, "code": "FFPROBE_JSON_ERROR", "error": str(exc), "path": path}
+    streams = payload.get("streams") if isinstance(payload, dict) else []
+    streams = streams if isinstance(streams, list) else []
+    video = next((stream for stream in streams if stream.get("codec_type") == "video"), {})
+    audio = next((stream for stream in streams if stream.get("codec_type") == "audio"), {})
+    return {"success": True, "path": path, "video": video, "audio": audio, "stream_count": len(streams)}
+
+
+def _proxy_media_signature(probe: Dict[str, Any]):
+    video = probe.get("video") if isinstance(probe.get("video"), dict) else {}
+    audio = probe.get("audio") if isinstance(probe.get("audio"), dict) else {}
+    width = _parse_int_text(video.get("width"))
+    height = _parse_int_text(video.get("height"))
+    return {
+        "path": probe.get("path"),
+        "codec": video.get("codec_name"),
+        "codec_long_name": video.get("codec_long_name"),
+        "profile": video.get("profile"),
+        "resolution": {"width": width, "height": height} if width and height else None,
+        "fps": _parse_rate(video.get("avg_frame_rate") or video.get("r_frame_rate")),
+        "frames": _parse_int_text(video.get("nb_frames") or (video.get("tags") or {}).get("NUMBER_OF_FRAMES")),
+        "sample_rate": _parse_int_text(audio.get("sample_rate")),
+        "channels": _parse_int_text(audio.get("channels")),
+    }
+
+
+def _add_proxy_resolution_mismatch(result: Dict[str, Any], source, proxy):
+    """Flag resolution only when the aspect ratio differs.
+
+    Proxies are routinely lower resolution than the source — Resolve links a
+    half/quarter-res proxy happily (that is the point of proxies; verified live
+    on Resolve Studio 21). Only a different aspect ratio means the file cannot
+    be a proxy of this source.
+    """
+    if not source or not proxy:
+        return
+    src_w, src_h = source.get("width"), source.get("height")
+    pxy_w, pxy_h = proxy.get("width"), proxy.get("height")
+    if not (src_w and src_h and pxy_w and pxy_h):
+        return
+    if (src_w, src_h) == (pxy_w, pxy_h):
+        return
+    src_aspect = src_w / src_h
+    pxy_aspect = pxy_w / pxy_h
+    if abs(src_aspect - pxy_aspect) / src_aspect <= 0.02:
+        result["warnings"].append(
+            f"Proxy is a same-aspect downscale ({src_w}x{src_h} -> {pxy_w}x{pxy_h})"
+        )
+        return
+    result["mismatches"].append({"field": "resolution", "source": source, "proxy": proxy})
+
+
+def _add_proxy_mismatch(mismatches: List[Dict[str, Any]], field: str, source, proxy, *, tolerance: float = 0.0):
+    if source is None or proxy is None:
+        return
+    if isinstance(source, (int, float)) and isinstance(proxy, (int, float)):
+        if abs(float(source) - float(proxy)) <= tolerance:
+            return
+    elif source == proxy:
+        return
+    mismatches.append({"field": field, "source": source, "proxy": proxy})
+
+
+def _check_proxy_media_compatibility(
+    clip,
+    proxy_path: str,
+    *,
+    expected_codec: Optional[str] = None,
+    expected_profile: Optional[str] = None,
+):
+    source = _clip_media_signature(clip)
+    probe = _probe_media_file(proxy_path)
+    proxy = _proxy_media_signature(probe) if probe.get("success") else {"path": proxy_path}
+    result = {
+        "success": bool(probe.get("success")),
+        "compatible": False,
+        "source": source,
+        "proxy": proxy,
+        "mismatches": [],
+        "warnings": [],
+    }
+    if not probe.get("success"):
+        result["error"] = probe.get("error", "Unable to probe proxy media")
+        result["code"] = probe.get("code", "FFPROBE_FAILED")
+        return result
+
+    _add_proxy_resolution_mismatch(result, source.get("resolution"), proxy.get("resolution"))
+    _add_proxy_mismatch(result["mismatches"], "fps", source.get("fps"), proxy.get("fps"), tolerance=0.01)
+    _add_proxy_mismatch(result["mismatches"], "frames", source.get("frames"), proxy.get("frames"), tolerance=1)
+    _add_proxy_mismatch(result["mismatches"], "sample_rate", source.get("sample_rate"), proxy.get("sample_rate"))
+
+    if expected_codec and not (
+        _media_token_matches(proxy.get("codec"), expected_codec)
+        or _media_token_matches(proxy.get("codec_long_name"), expected_codec)
+    ):
+        result["mismatches"].append({
+            "field": "expected_codec",
+            "expected": expected_codec,
+            "proxy": proxy.get("codec") or proxy.get("codec_long_name"),
+        })
+    if expected_profile and not _media_token_matches(proxy.get("profile"), expected_profile):
+        result["mismatches"].append({
+            "field": "expected_profile",
+            "expected": expected_profile,
+            "proxy": proxy.get("profile"),
+        })
+
+    result["compatible"] = not result["mismatches"]
+    if source.get("resolution") is None:
+        result["warnings"].append("Source clip resolution was not available from GetClipProperty")
+    if source.get("fps") is None:
+        result["warnings"].append("Source clip FPS was not available from GetClipProperty")
+    if proxy.get("frames") is None:
+        result["warnings"].append("Proxy frame count was not available from ffprobe")
+    return result
+
+
+def _proxy_link_readback(clip):
+    properties, properties_error = _safe_clip_call(clip, "GetClipProperty", "")
+    properties = properties if isinstance(properties, dict) else {}
+    readback = {"clip_properties": properties}
+    if properties_error:
+        readback["properties_error"] = properties_error
+    proxy_keys = [
+        "Proxy",
+        "Proxy Media",
+        "Proxy Media Path",
+        "Proxy Path",
+        "Proxy Status",
+        "ProxyMediaPath",
+    ]
+    observed = {key: properties.get(key) for key in proxy_keys if key in properties}
+    if observed:
+        readback["proxy_fields"] = observed
+    return readback
+
+
+def _normalized_path_for_compare(path):
+    if not path or not isinstance(path, str):
+        return None
+    return os.path.normcase(os.path.abspath(os.path.expanduser(path)))
+
+
+def _proxy_readback_matches_path(readback: Dict[str, Any], proxy_path: str):
+    expected = _normalized_path_for_compare(proxy_path)
+    if not expected:
+        return False
+    proxy_fields = readback.get("proxy_fields") if isinstance(readback, dict) else {}
+    proxy_fields = proxy_fields if isinstance(proxy_fields, dict) else {}
+    for value in proxy_fields.values():
+        if _normalized_path_for_compare(value) == expected:
+            return True
+    return False
+
+
+def _proxy_link_journal_event(event_type: str, clip, proxy_path: str, *, success=None, verified=False, compatibility=None):
+    event = {
+        "type": event_type,
+        "clip_id": _safe_media_pool_item_id(clip),
+        "clip_name": _safe_media_pool_item_name(clip),
+        "proxy_path": proxy_path,
+        "success": success,
+        "verified": bool(verified),
+    }
+    if compatibility is not None:
+        event["compatible"] = bool(compatibility.get("compatible"))
+        if compatibility.get("mismatches"):
+            event["mismatch_fields"] = [row.get("field") for row in compatibility.get("mismatches", [])]
+    return event
+
+
+def _verified_operation(
+    name: str,
+    *,
+    requested: Dict[str, Any],
+    preflight: Dict[str, Any],
+    execution: Dict[str, Any],
+    verification_status: str,
+    readback=None,
+    journal_event=None,
+):
+    return {
+        "name": name,
+        "preflight": preflight,
+        "requested": requested,
+        "execution": execution,
+        "readback": readback,
+        "verified": verification_status == "readback_verified",
+        "verification_status": verification_status,
+        "journal_event": journal_event,
+    }
+
+
+def _check_proxy_media_compatibility_checked(root, p: Dict[str, Any]):
+    clip = _find_clip(root, p.get("clip_id", ""))
+    if not clip:
+        return _err(f"Clip not found: {p.get('clip_id')}")
+    proxy_path = p.get("proxy_path") or p.get("path")
+    path_err = _path_error(proxy_path, must_be_file=True)
+    if path_err:
+        return _err(path_err)
+    return _check_proxy_media_compatibility(
+        clip,
+        proxy_path,
+        expected_codec=p.get("expected_codec") or p.get("codec"),
+        expected_profile=p.get("expected_profile") or p.get("profile"),
+    )
+
+
+def _timeline_append_readback_snapshot(proj):
+    try:
+        tl = proj.GetCurrentTimeline() if proj else None
+    except Exception as exc:
+        return {"available": False, "error": f"GetCurrentTimeline failed: {exc}"}
+    if not tl:
+        return {"available": False, "error": "No current timeline"}
+
+    timeline = {}
+    try:
+        timeline["name"] = tl.GetName()
+    except Exception:
+        timeline["name"] = None
+    try:
+        timeline["id"] = tl.GetUniqueId()
+    except Exception:
+        timeline["id"] = None
+
+    tracks = {}
+    item_count = 0
+    warnings = []
+    for track_type in ("video", "audio", "subtitle"):
+        track_count = _timeline_track_count(tl, track_type)
+        rows = []
+        for track_index in range(1, track_count + 1):
+            try:
+                items = tl.GetItemListInTrack(track_type, track_index) or []
+            except Exception as exc:
+                warnings.append(f"GetItemListInTrack({track_type}, {track_index}) failed: {exc}")
+                items = []
+            item_count += len(items)
+            rows.append({
+                "track_index": track_index,
+                "item_count": len(items),
+                "item_ids": _timeline_item_ids(items),
+            })
+        tracks[track_type] = {"track_count": track_count, "tracks": rows}
+    return {
+        "available": True,
+        "timeline": timeline,
+        "item_count": item_count,
+        "tracks": tracks,
+        "warnings": warnings,
+    }
+
+
+def _compare_timeline_append_readback(before, observed, expected_count: int):
+    before_count = before.get("item_count") if isinstance(before, dict) and before.get("available") else None
+    after_count = observed.get("item_count") if isinstance(observed, dict) and observed.get("available") else None
+    delta = after_count - before_count if before_count is not None and after_count is not None else None
+    return {
+        "verified": delta is not None and delta >= expected_count and expected_count > 0,
+        "before_item_count": before_count,
+        "after_item_count": after_count,
+        "item_count_delta": delta,
+        "expected_item_count_delta": expected_count,
+    }
+
+
+def _append_to_timeline_with_verification(proj, mp, append_payload, requested: Dict[str, Any], expected_count: int):
+    raw_result = {"value": None}
+    before = _timeline_append_readback_snapshot(proj)
+
+    def mutate():
+        raw_result["value"] = mp.AppendToTimeline(append_payload)
+        return bool(raw_result["value"])
+
+    verification = verify_by_readback(
+        mutate=mutate,
+        observe=lambda: _timeline_append_readback_snapshot(proj),
+        snapshot=lambda: before,
+        compare=lambda before_snapshot, observed: _compare_timeline_append_readback(
+            before_snapshot,
+            observed,
+            expected_count,
+        ),
+        intent=requested,
+        label="media_pool.append_to_timeline",
+    )
+    return raw_result["value"], verification, before
+
+
+def _append_to_timeline_verified_operation(requested: Dict[str, Any], verification: Dict[str, Any], before):
+    success = bool(verification.get("success_raw"))
+    verified = bool(verification.get("verified"))
+    verification_status = "readback_verified" if verified else ("api_failed" if not success else "api_success_unverified")
+    readback = {
+        "before": before,
+        "after": verification.get("observed"),
+        "before_item_count": verification.get("before_item_count"),
+        "after_item_count": verification.get("after_item_count"),
+        "item_count_delta": verification.get("item_count_delta"),
+        "expected_item_count_delta": verification.get("expected_item_count_delta"),
+    }
+    return _verified_operation(
+        "media_pool.append_to_timeline",
+        requested=requested,
+        preflight={
+            "ok": True,
+            "current_timeline_available": bool(isinstance(before, dict) and before.get("available")),
+            "expected_item_count_delta": requested.get("expected_count"),
+        },
+        execution={"api": "MediaPool.AppendToTimeline", "attempted": True, "success": success},
+        readback=readback,
+        verification_status=verification_status,
+        journal_event={
+            "type": "timeline.appended" if verified else ("timeline.append.failed" if not success else "timeline.append.unverified"),
+            "success": success,
+            "verified": verified,
+            "expected_count": requested.get("expected_count"),
+            "item_count_delta": verification.get("item_count_delta"),
+        },
+    )
+
+
 def _link_proxy_checked(root, p: Dict[str, Any]):
     clip = _find_clip(root, p.get("clip_id", ""))
     if not clip:
@@ -9967,9 +10484,123 @@ def _link_proxy_checked(root, p: Dict[str, Any]):
     path_err = _path_error(proxy_path, must_be_file=True)
     if path_err:
         return _err(path_err)
+    missing = _requires_method(clip, "LinkProxyMedia", "17.0")
+    if missing:
+        return missing
+    check_compatibility = bool(
+        p.get("check_compatibility")
+        or p.get("require_compatible")
+        or p.get("expected_codec")
+        or p.get("expected_profile")
+        or p.get("codec")
+        or p.get("profile")
+    )
+    compatibility = None
+    if check_compatibility:
+        compatibility = _check_proxy_media_compatibility(
+            clip,
+            proxy_path,
+            expected_codec=p.get("expected_codec") or p.get("codec"),
+            expected_profile=p.get("expected_profile") or p.get("profile"),
+        )
+    requested = {
+        "clip_id": p.get("clip_id"),
+        "proxy_path": proxy_path,
+        "dry_run": bool(p.get("dry_run")),
+        "check_compatibility": check_compatibility,
+        "require_compatible": bool(p.get("require_compatible")),
+        "expected_codec": p.get("expected_codec") or p.get("codec"),
+        "expected_profile": p.get("expected_profile") or p.get("profile"),
+    }
+    preflight = {
+        "ok": True,
+        "clip_found": True,
+        "proxy_path_valid": True,
+        "method_available": True,
+        "compatibility_checked": compatibility is not None,
+    }
+    if compatibility is not None:
+        preflight["compatible"] = bool(compatibility.get("compatible"))
     if p.get("dry_run"):
-        return _ok(clip=_media_pool_item_summary(clip), proxy_path=proxy_path)
-    return {"success": bool(clip.LinkProxyMedia(proxy_path))}
+        out = _ok(clip=_media_pool_item_summary(clip), proxy_path=proxy_path)
+        if compatibility is not None:
+            out["compatibility"] = compatibility
+        out["verified_operation"] = _verified_operation(
+            "media_pool.link_proxy_checked",
+            requested=requested,
+            preflight=preflight,
+            execution={"api": "MediaPoolItem.LinkProxyMedia", "attempted": False, "success": None},
+            readback=None,
+            verification_status="dry_run",
+            journal_event=_proxy_link_journal_event(
+                "proxy.link.preview",
+                clip,
+                proxy_path,
+                success=None,
+                verified=False,
+                compatibility=compatibility,
+            ),
+        )
+        return out
+    if p.get("require_compatible") and compatibility is not None and not compatibility.get("compatible"):
+        out = _err(
+            "Proxy media is not compatible with the source clip; refusing LinkProxyMedia",
+            code="PROXY_INCOMPATIBLE",
+            category="invalid_input",
+            remediation="Use a proxy with matching resolution, FPS, frame count, sample rate, and requested codec/profile.",
+        )
+        out["compatibility"] = compatibility
+        out["verified_operation"] = _verified_operation(
+            "media_pool.link_proxy_checked",
+            requested=requested,
+            preflight={**preflight, "ok": False},
+            execution={"api": "MediaPoolItem.LinkProxyMedia", "attempted": False, "success": None},
+            readback=None,
+            verification_status="blocked",
+            journal_event=_proxy_link_journal_event(
+                "proxy.link.blocked",
+                clip,
+                proxy_path,
+                success=False,
+                verified=False,
+                compatibility=compatibility,
+            ),
+        )
+        return out
+    verification = verify_by_readback(
+        mutate=lambda: clip.LinkProxyMedia(proxy_path),
+        observe=lambda: _proxy_link_readback(clip),
+        compare=lambda _before, observed: {
+            "verified": _proxy_readback_matches_path(observed, proxy_path),
+        },
+        intent={"clip_id": p.get("clip_id"), "proxy_path": proxy_path},
+        label="media_pool.link_proxy_checked",
+    )
+    success = bool(verification.get("success_raw"))
+    readback = verification.get("observed")
+    verified = bool(verification.get("verified"))
+    verification_status = "readback_verified" if verified else ("api_failed" if not success else "api_success_unverified")
+    event_type = "proxy.linked" if success else "proxy.link.failed"
+    out = {"success": success, "readback": readback}
+    if compatibility is not None:
+        out["compatibility"] = compatibility
+    out["verified_operation"] = _verified_operation(
+        "media_pool.link_proxy_checked",
+        requested=requested,
+        preflight=preflight,
+        execution={"api": "MediaPoolItem.LinkProxyMedia", "attempted": True, "success": success},
+        readback=readback,
+        verification_status=verification_status,
+        journal_event=_proxy_link_journal_event(
+            event_type,
+            clip,
+            proxy_path,
+            success=success,
+            verified=verified,
+            compatibility=compatibility,
+        ),
+    )
+    return out
 
 
 def _link_full_resolution_checked(root, p: Dict[str, Any]):
@@ -12553,6 +13184,35 @@ class _SpecLiveExecutor:
         self._spec = spec
         self._proj = pm.GetCurrentProject()
 
+    def _media_pool_bin_paths(self) -> List[str]:
+        if not self._proj or not getattr(self._spec, "bins", None):
+            return []
+        try:
+            mp = self._proj.GetMediaPool()
+            root = mp.GetRootFolder() if mp else None
+        except Exception:
+            return []
+        if root is None:
+            return []
+        paths: List[str] = []
+
+        def walk(folder, prefix: str) -> None:
+            paths.append(prefix)
+            try:
+                subfolders = folder.GetSubFolderList() or []
+            except Exception:
+                subfolders = []
+            for subfolder in subfolders:
+                try:
+                    name = subfolder.GetName()
+                except Exception:
+                    name = ""
+                if name:
+                    walk(subfolder, f"{prefix}/{name}")
+
+        walk(root, "Master")
+        return paths
+
     def live_state(self) -> Dict[str, Any]:
         proj = self._proj
         projects = list(self._pm.GetProjectListInCurrentFolder() or [])
@@ -12602,6 +13262,7 @@ class _SpecLiveExecutor:
             "project": proj.GetName() if proj else None,
             "projects": projects,
             "settings": settings,
+            "bins": self._media_pool_bin_paths(),
             "timelines": timelines,
         }
 
@@ -12623,6 +13284,18 @@ class _SpecLiveExecutor:
         except Exception:
             return False
 
+    def ensure_bin(self, path: str) -> bool:
+        if not self._proj:
+            return False
+        try:
+            mp = self._proj.GetMediaPool()
+        except Exception:
+            return False
+        if mp is None:
+            return False
+        _, err = _ensure_folder_path(mp, path)
+        return err is None
+
     def ensure_timeline(self, name: str, fps: Optional[float]) -> bool:
         if not self._proj:
             return False
@@ -12751,13 +13424,36 @@ def _project_lint_live(r, pm) -> Dict[str, Any]:
         except Exception:
             pass
         item_count = 0
+        video_item_count = 0
+        audio_item_count = 0
+        subtitle_item_count = 0
         try:
-            vc = int(tl.GetTrackCount("video") or 0)
-            for ti in range(1, vc + 1):
-                item_count += len(tl.GetItemListInTrack("video", ti) or [])
+            for track_type, key in (
+                ("video", "video_item_count"),
+                ("audio", "audio_item_count"),
+                ("subtitle", "subtitle_item_count"),
+            ):
+                track_total = 0
+                track_count = int(tl.GetTrackCount(track_type) or 0)
+                for ti in range(1, track_count + 1):
+                    track_total += len(tl.GetItemListInTrack(track_type, ti) or [])
+                if key == "video_item_count":
+                    video_item_count = track_total
+                elif key == "audio_item_count":
+                    audio_item_count = track_total
+                elif key == "subtitle_item_count":
+                    subtitle_item_count = track_total
+                item_count += track_total
         except Exception:
             pass
-        timelines.append({"name": tl.GetName(), "fps": fps, "item_count": item_count})
+        timelines.append({
+            "name": tl.GetName(),
+            "fps": fps,
+            "item_count": item_count,
+            "video_item_count": video_item_count,
+            "audio_item_count": audio_item_count,
+            "subtitle_item_count": subtitle_item_count,
+        })
     state["timelines"] = timelines
     settings: Dict[str, Any] = {}
     try:
@@ -13823,7 +14519,8 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
       metadata_field_inventory(clip_ids|selected, include_values?) -> {items, ui_group_names}
       safe_relink(clip_ids|selected, folder_path, dry_run?) -> {success}
       safe_unlink(clip_ids|selected, dry_run?) -> {success}
-      link_proxy_checked(clip_id, proxy_path|path, dry_run?) -> {success}
+      check_proxy_media_compatibility(clip_id, proxy_path|path, expected_codec?, expected_profile?) -> {compatible, mismatches}
+      link_proxy_checked(clip_id, proxy_path|path, dry_run?, check_compatibility?, require_compatible?, expected_codec?, expected_profile?) -> {success}
       link_full_resolution_checked(clip_id, path|full_res_media_path, dry_run?) -> {success}
       set_clip_marks(clip_ids|selected, mark_in, mark_out, type?, dry_run?) -> {success, results}
       clear_clip_marks(clip_ids|selected, type?, dry_run?) -> {success, results}
@@ -13965,7 +14662,18 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
                 if row_err:
                     return row_err
                 built.append(row)
-            result = mp.AppendToTimeline(built)
+            requested = {
+                "mode": "clip_infos",
+                "clip_info_count": len(raw),
+                "expected_count": len(built),
+            }
+            result, verification, before = _append_to_timeline_with_verification(
+                proj,
+                mp,
+                built,
+                requested,
+                len(built),
+            )
             if not result:
                 return _err("Failed to append clip_infos to timeline")
             items_out = []
@@ -13974,14 +14682,38 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
                 if item_err:
                     return item_err
                 items_out.append(item_out)
-            return _ok(count=len(result), items=items_out)
+            out = _ok(count=len(result), items=items_out)
+            out["verified_operation"] = _append_to_timeline_verified_operation(
+                requested,
+                verification,
+                before,
+            )
+            return out
         clip_ids = p.get("clip_ids")
         if not clip_ids:
             return _err("Provide clip_ids (simple append) or clip_infos (positioned append)")
         clips = [_find_clip(root, cid) for cid in clip_ids]
         clips = [c for c in clips if c]
-        result = mp.AppendToTimeline(clips)
-        return _ok(count=len(result) if result else 0)
+        requested = {
+            "mode": "clip_ids",
+            "clip_ids": list(clip_ids),
+            "resolved_clip_count": len(clips),
+            "expected_count": len(clips),
+        }
+        result, verification, before = _append_to_timeline_with_verification(
+            proj,
+            mp,
+            clips,
+            requested,
+            len(clips),
+        )
+        out = _ok(count=len(result) if result else 0)
+        out["verified_operation"] = _append_to_timeline_verified_operation(
+            requested,
+            verification,
+            before,
+        )
+        return out
     elif action == "import_media":
         if p.get("clip_infos") is not None:
             raw = p["clip_infos"]
@@ -14086,6 +14818,8 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
         return _safe_relink(mp, root, p)
     elif action == "safe_unlink":
         return _safe_unlink(mp, root, p)
+    elif action == "check_proxy_media_compatibility":
+        return _check_proxy_media_compatibility_checked(root, p)
     elif action == "link_proxy_checked":
         return _link_proxy_checked(root, p)
     elif action == "link_full_resolution_checked":
@@ -16330,6 +17064,7 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       apply_look_to_items(target_ids, cdl?|copy_from_item_id?, dry_run?) -> {success}
         # example: action_help(name='<action_name>')
       thumbnail_contact_sheet(frames?|max_samples?, analysis_root?) -> {path, samples}
+        frames are relative to the timeline start (frame 0 = first frame), like marker frameIds.
       marker_thumbnail_review(max_samples?, analysis_root?) -> {path, samples, review_guidance}
       edit_kernel_capabilities() -> {supported, partially_supported, unsupported}
       probe_edit_kernel_item(clip_ids? selected? timeline_item?) -> {items, count}
@@ -16936,6 +17671,12 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
 def timeline_markers(action: str, params: Optional[Dict[str, Any]] = None) -> Any:
     """Markers and playhead operations on the current timeline.
 
+    Marker frames are RELATIVE to the timeline start: frame 0 is the first
+    frame of the timeline, even when the timeline starts at 01:00:00:00.
+    Timecode params are absolute timeline timecode as shown in the Resolve UI
+    (timecodes before the start timecode are treated as elapsed time) and are
+    converted to relative frames automatically.
+
     Actions:
       add(frame|frame_id|frameId|timecode?, color?, name?, note?, duration?, custom_data?) -> {success, frame}
         If frame/timecode is omitted, add uses the current playhead timecode.

package/src/utils/project_lint.py

@@ -50,6 +50,15 @@ def _color_science_unset(settings: Dict[str, Any]) -> bool:
     return mode in ("", "davinciYRGB")
 
 
+def _timeline_has_items(timeline: Dict[str, Any]) -> bool:
+    if int(timeline.get("item_count") or 0) > 0:
+        return True
+    for key in ("video_item_count", "audio_item_count", "subtitle_item_count"):
+        if int(timeline.get(key) or 0) > 0:
+            return True
+    return False
+
+
 def lint_state(state: Dict[str, Any]) -> List[Issue]:
     """Return graded issues for a project state dict, most-severe first."""
     issues: List[Issue] = []
@@ -73,7 +82,7 @@ def lint_state(state: Dict[str, Any]) -> List[Issue]:
         ))
 
     for tl in timelines:
-        if (tl.get("item_count") or 0) == 0:
+        if not _timeline_has_items(tl):
             issues.append(Issue(
                 "warning", "empty_timeline",
                 f"Timeline '{tl.get('name')}' has no clips.",

package/src/utils/project_spec.py

@@ -83,6 +83,7 @@ class Spec:
     project: str
     color_preset: Optional[str] = None
     settings: Dict[str, str] = field(default_factory=dict)
+    bins: List[str] = field(default_factory=list)
     timelines: List[TimelineSpec] = field(default_factory=list)
     hooks: List[Hook] = field(default_factory=list)
 
@@ -145,6 +146,20 @@ def spec_from_dict(data: Dict[str, Any]) -> Spec:
     if not isinstance(settings, dict):
         raise SpecError("`settings` must be a mapping.")
 
+    bins: List[str] = []
+    for raw_bin in data.get("bins") or []:
+        if isinstance(raw_bin, str) and raw_bin.strip():
+            bin_path = raw_bin.strip().strip("/")
+        elif isinstance(raw_bin, dict) and raw_bin.get("path"):
+            bin_path = str(raw_bin["path"]).strip().strip("/")
+        else:
+            raise SpecError(f"Each bin needs a non-empty path: {raw_bin!r}")
+        # Live bin paths are always reported Master-prefixed; normalize here so
+        # an unprefixed spec bin doesn't read as a perpetually-pending change.
+        if bin_path != "Master" and not bin_path.startswith("Master/"):
+            bin_path = f"Master/{bin_path}"
+        bins.append(bin_path)
+
     timelines: List[TimelineSpec] = []
     for raw_tl in (data.get("timelines") or []):
         if not isinstance(raw_tl, dict) or not raw_tl.get("name"):
@@ -160,6 +175,7 @@ def spec_from_dict(data: Dict[str, Any]) -> Spec:
         project=str(project),
         color_preset=preset,
         settings={str(k): str(v) for k, v in settings.items()},
+        bins=bins,
         timelines=timelines,
         hooks=_parse_hooks(data.get("hooks")),
     )
@@ -252,6 +268,15 @@ def plan_spec(spec: Spec, live: Dict[str, Any]) -> Dict[str, Any]:
                 f"{live_settings.get(key)!r} -> {want!r}", {"key": key, "value": want},
             ))
 
+    # Media Pool bins. Paths are slash-delimited from Master, e.g.
+    # "Master/Media/Scene_01"; creation is idempotent in the executor.
+    live_bins = set(live.get("bins") or [])
+    for bin_path in spec.bins:
+        if bin_path in live_bins:
+            actions.append(Action("noop", f"bin:{bin_path}", "exists"))
+        else:
+            actions.append(Action("ensure", f"bin:{bin_path}", "ensure media-pool bin", {"path": bin_path}))
+
     # Timelines + their settings + markers. NOTE: `fps` is a *creation-time*
     # property handled by ensure_timeline — Resolve refuses SetSetting on
     # timelineFrameRate after a timeline exists — so it is never emitted as a
@@ -300,6 +325,7 @@ def _spec_desired_state(spec: Spec) -> Dict[str, Any]:
     return {
         "project": spec.project,
         "settings": {k: _norm_setting_value(v) for k, v in effective_settings(spec).items()},
+        "bins": list(spec.bins),
         "timelines": [
             {
                 "name": tl.name,
@@ -324,6 +350,7 @@ def _spec_normalized_state(live: Dict[str, Any], spec: Spec) -> Dict[str, Any]:
     return {
         "project": live.get("project"),
         "settings": {k: _norm_setting_value(live_settings.get(k)) for k in desired if k in live_settings},
+        "bins": [path for path in (live.get("bins") or []) if path in set(spec.bins)],
         "timelines": [
             {
                 "name": name,
@@ -356,6 +383,7 @@ def apply_spec(
         ensure_timeline(name, fps) -> bool
         set_timeline_setting(timeline_name, key, value) -> bool
         add_marker(timeline_name, marker: dict) -> bool
+        ensure_bin(path) -> bool
 
     Hooks execute only when `run_hooks=True` AND a `run_hook` callable is given —
     arbitrary shell from a spec stays opt-in. Failures accumulate when
@@ -397,6 +425,9 @@ def apply_spec(
         _record(bool(executor.set_project_setting(key, desired[key])),
                 f"project:{spec.project}/setting:{key}", str(desired[key]))
 
+    for bin_path in spec.bins:
+        _record(bool(executor.ensure_bin(bin_path)), f"bin:{bin_path}")
+
     # Timelines. `fps` is creation-time only (ensure_timeline); never set as a
     # post-creation timelineFrameRate setting — Resolve refuses that.
     live_tls = {tl.get("name"): tl for tl in (live.get("timelines") or [])}