davinci-resolve-mcp 4.7.8 → 4.7.10

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 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 v4.7.10 — drop-frame sync events are reported at the timecode they happen
+
+### Fixed
+
+- **A sync event on a drop-frame clip was reported 3.6 seconds per hour early, and
+  rendered as non-drop.** ([#248](https://github.com/samuelgursky/davinci-resolve-mcp/pull/248), @Dev-next-gen)
+  `_timecode_for_event` reports an event at `start_timecode + offset`, where the start
+  timecode comes from the media's own timecode track via ffprobe and on an NTSC
+  deliverable is routinely drop-frame (`HH:MM:SS;FF`). `timecode_to_frames` honours
+  drop-frame (`01:00:00;00` at 29.97 is frame 107892), but the detector's private
+  `_frames_to_timecode` had no drop-frame arithmetic, so the frame numbers subtracted
+  on the way in were never added back: the head of a drop-frame clip came back as
+  `00:59:56:12`. That value is appended to the marker note written into the Resolve
+  project — the thing someone reads to line two cameras up off a 2-pop. The inverse
+  now lives next to the forward conversion in `src/utils/multicam.py` as
+  `frames_to_timecode`, so the pair cannot drift apart again, and `sync_detection`
+  carries the drop-frame spelling of the start timecode through to it. Non-drop
+  timecode is deliberately unchanged (29.97 colon timecode legitimately lags the wall
+  clock), and a semicolon at 23.976 still drops nothing because drop-frame is only
+  defined at nominal 30 and 60. Verified on landing by brute force against the forward
+  conversion: two hours at 29.97 (216,000 frames) and 59.94 (432,000 frames), zero
+  round-trip violations, every timecode unique, dropped numbers never at the top of a
+  non-tenth minute. Guard test: `tests/test_sync_event_timecode.py`.
+
+## What's New in v4.7.9 — a negative still, album or item index is refused
+
+### Fixed
+
+- **A negative index acted on the last element instead of being refused.** ([#247](https://github.com/samuelgursky/davinci-resolve-mcp/pull/247), @Dev-next-gen)
+  Python reads `items[-1]` as the last item, and several lookups bounded an index with
+  `>= len(...)` only. The granular `_get_timeline_item` — which 85 granular tools go
+  through — had exactly the gap EX5 closed in the compound `_get_item`, so
+  `item_index=-1` acted on the last clip of the track. Every album and still lookup in
+  the compound `gallery` / `gallery_stills` tools and in `src/granular/gallery.py` had
+  the same one-sided check. Sharpest case: `gallery_stills delete_stills` and granular
+  `delete_stills_from_album` with `still_indices=[-1]` deleted the album's LAST still,
+  and an out-of-range index was silently dropped while the others were deleted and the
+  call reported success. The lower bound is now in the granular resolver and gallery
+  lookups, a small `_index_in_range` helper guards the compound gallery tools, and the
+  two delete paths refuse the whole call when any index is not a 0-based position
+  (the way `ti_copy_grades` treats its target list) rather than deleting a set nobody
+  asked for. Valid indices behave exactly as before; the one visible change is that a
+  partly invalid `still_indices` list now errors instead of partially deleting. Guard
+  test: `tests/test_negative_index_refused.py` drives the real tool bodies against fake
+  gallery and timeline objects; 16 subtests fail on the previous code.
+
 ## What's New in v4.7.8 — `allow_non_mcp_name="false"` no longer lifts the `_mcp_` name guard
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.7.8-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.7.10-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-37%20(389%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-4.7.8-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.7.10-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-37%20(389%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v4.7.8 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.7.10 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/install.py

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

package/src/granular/common.py

@@ -93,7 +93,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.7.8"
+VERSION = "4.7.10"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")
@@ -810,7 +810,9 @@ def _get_timeline_item(track_type="video", track_index=1, item_index=0):
     if err:
         return None, err
     items = tl.GetItemListInTrack(track_type, track_index)
-    if not items or item_index >= len(items):
+    # Reject negatives: `items[-1]` is the LAST clip, so a negative index would
+    # act on a clip nobody named (EX5 fixed the compound `_get_item`, not this twin).
+    if not items or item_index < 0 or item_index >= len(items):
         return None, {"error": f"No item at index {item_index} on {track_type} track {track_index}"}
     return items[item_index], None
 

package/src/granular/gallery.py

@@ -4,6 +4,18 @@ from src.granular.common import *  # noqa: F401,F403
 
 resolve = ResolveProxy()
 
+
+def _index_in_range(idx, length):
+    """True for a real 0-based position. Negatives are refused: Python would read
+    `albums[-1]` as the last album and act on something nobody named."""
+    return isinstance(idx, int) and not isinstance(idx, bool) and 0 <= idx < length
+
+
+def _invalid_indices(indices, length):
+    """The entries of `indices` that are not a 0-based position below `length`."""
+    return [i for i in indices if not _index_in_range(i, length)]
+
+
 @mcp.tool(annotations=READ_ONLY_TOOL)
 def get_gallery_album_name() -> Dict[str, Any]:
     """Get the name of the current gallery album."""
@@ -107,7 +119,7 @@ def set_current_still_album(album_index: int) -> Dict[str, Any]:
     if not gallery:
         return {"error": "Failed to get Gallery"}
     albums = gallery.GetGalleryStillAlbums()
-    if not albums or album_index >= len(albums):
+    if not albums or album_index < 0 or album_index >= len(albums):
         return {"error": f"No album at index {album_index}"}
     result = gallery.SetCurrentStillAlbum(albums[album_index])
     return {"success": bool(result)}
@@ -176,7 +188,7 @@ def get_album_stills(album_index: int = 0) -> Dict[str, Any]:
     if not gallery:
         return {"error": "Failed to get Gallery"}
     albums = gallery.GetGalleryStillAlbums()
-    if not albums or album_index >= len(albums):
+    if not albums or album_index < 0 or album_index >= len(albums):
         return {"error": f"No album at index {album_index}"}
     stills = albums[album_index].GetStills()
     return {"still_count": len(stills) if stills else 0}
@@ -198,10 +210,10 @@ def get_still_label(album_index: int, still_index: int) -> Dict[str, Any]:
         return {"error": "No project open"}
     gallery = project.GetGallery()
     albums = gallery.GetGalleryStillAlbums()
-    if not albums or album_index >= len(albums):
+    if not albums or album_index < 0 or album_index >= len(albums):
         return {"error": f"No album at index {album_index}"}
     stills = albums[album_index].GetStills()
-    if not stills or still_index >= len(stills):
+    if not stills or still_index < 0 or still_index >= len(stills):
         return {"error": f"No still at index {still_index}"}
     label = albums[album_index].GetLabel(stills[still_index])
     return {"label": label if label else ""}
@@ -225,10 +237,10 @@ def set_still_label(album_index: int, still_index: int, label: str) -> Dict[str,
         return {"error": "No project open"}
     gallery = project.GetGallery()
     albums = gallery.GetGalleryStillAlbums()
-    if not albums or album_index >= len(albums):
+    if not albums or album_index < 0 or album_index >= len(albums):
         return {"error": f"No album at index {album_index}"}
     stills = albums[album_index].GetStills()
-    if not stills or still_index >= len(stills):
+    if not stills or still_index < 0 or still_index >= len(stills):
         return {"error": f"No still at index {still_index}"}
     result = albums[album_index].SetLabel(stills[still_index], label)
     return {"success": bool(result)}
@@ -250,7 +262,7 @@ def import_stills_to_album(album_index: int, file_paths: List[str]) -> Dict[str,
         return {"error": "No project open"}
     gallery = project.GetGallery()
     albums = gallery.GetGalleryStillAlbums()
-    if not albums or album_index >= len(albums):
+    if not albums or album_index < 0 or album_index >= len(albums):
         return {"error": f"No album at index {album_index}"}
     result = albums[album_index].ImportStills(file_paths)
     return {"success": bool(result)}
@@ -274,7 +286,7 @@ def export_stills_from_album(album_index: int, folder_path: str, file_prefix: st
         return {"error": "No project open"}
     gallery = project.GetGallery()
     albums = gallery.GetGalleryStillAlbums()
-    if not albums or album_index >= len(albums):
+    if not albums or album_index < 0 or album_index >= len(albums):
         return {"error": f"No album at index {album_index}"}
     stills = albums[album_index].GetStills()
     if not stills:
@@ -300,11 +312,17 @@ def delete_stills_from_album(album_index: int, still_indices: List[int]) -> Dict
         return {"error": "No project open"}
     gallery = project.GetGallery()
     albums = gallery.GetGalleryStillAlbums()
-    if not albums or album_index >= len(albums):
+    if not albums or album_index < 0 or album_index >= len(albums):
         return {"error": f"No album at index {album_index}"}
     stills = albums[album_index].GetStills()
     if not stills:
         return {"error": "No stills in album"}
-    to_delete = [stills[i] for i in still_indices if i < len(stills)]
+    # A negative index is a real Python index (`stills[-1]` is the last still),
+    # and an out-of-range one used to be dropped while the rest were deleted.
+    # Refuse the whole call instead of deleting a set nobody asked for.
+    invalid = _invalid_indices(still_indices, len(stills))
+    if invalid:
+        return {"error": f"still_indices out of range for {len(stills)} stills: {invalid}"}
+    to_delete = [stills[i] for i in still_indices]
     result = albums[album_index].DeleteStills(to_delete)
     return {"success": bool(result)}

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "4.7.8"
+VERSION = "4.7.10"
 
 import base64
 import os
@@ -28848,6 +28848,17 @@ def timeline_item_takes(action: str, params: Optional[Dict[str, Any]] = None) ->
     return _unknown(action, ["add","get_count","get_selected_index","get_by_index","select","delete","finalize"])
 
 
+def _index_in_range(idx, length):
+    """True for a real 0-based position. Negatives are refused: Python would read
+    `albums[-1]` as the last album and act on something nobody named."""
+    return isinstance(idx, int) and not isinstance(idx, bool) and 0 <= idx < length
+
+
+def _invalid_indices(indices, length):
+    """The entries of `indices` that are not a 0-based position below `length`."""
+    return [i for i in indices if not _index_in_range(i, length)]
+
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # TOOL 23: gallery
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -28881,13 +28892,13 @@ def gallery(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, A
     if action == "get_album_name":
         albums = gal.GetGalleryStillAlbums() or []
         idx = p.get("album_index", 0)
-        if idx < len(albums):
+        if _index_in_range(idx, len(albums)):
             return {"name": gal.GetAlbumName(albums[idx])}
         return _err("Album index out of range")
     elif action == "set_album_name":
         albums = gal.GetGalleryStillAlbums() or []
         idx = p.get("album_index", 0)
-        if idx < len(albums):
+        if _index_in_range(idx, len(albums)):
             return {"success": bool(gal.SetAlbumName(albums[idx], p["name"]))}
         return _err("Album index out of range")
     elif action == "get_current_album":
@@ -28896,7 +28907,7 @@ def gallery(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, A
     elif action == "set_current_album":
         albums = gal.GetGalleryStillAlbums() or []
         idx = p.get("album_index", 0)
-        if idx < len(albums):
+        if _index_in_range(idx, len(albums)):
             return {"success": bool(gal.SetCurrentStillAlbum(albums[idx]))}
         return _err("Album index out of range")
     elif action == "get_still_albums":
@@ -28964,7 +28975,7 @@ def gallery_stills(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
     album_idx = p.get("album_index")
     if album_idx is not None:
         albums = gal.GetGalleryStillAlbums() or []
-        if album_idx < len(albums):
+        if _index_in_range(album_idx, len(albums)):
             album = albums[album_idx]
         else:
             return _err("Album index out of range")
@@ -28982,13 +28993,13 @@ def gallery_stills(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
     elif action == "get_label":
         stills = album.GetStills() or []
         idx = p.get("still_index", 0)
-        if idx < len(stills):
+        if _index_in_range(idx, len(stills)):
             return {"label": album.GetLabel(stills[idx])}
         return _err("Still index out of range")
     elif action == "set_label":
         stills = album.GetStills() or []
         idx = p.get("still_index", 0)
-        if idx < len(stills):
+        if _index_in_range(idx, len(stills)):
             return {"success": bool(album.SetLabel(stills[idx], p["label"]))}
         return _err("Still index out of range")
     elif action == "import_stills":
@@ -29119,8 +29130,15 @@ def gallery_stills(action: str, params: Optional[Dict[str, Any]] = None) -> Dict
         return {"files": file_details, "format": used_format, "folder": folder_path, "cleaned_up": cleanup}
     elif action == "delete_stills":
         stills = album.GetStills() or []
-        to_delete = [stills[i] for i in p["still_indices"] if i < len(stills)]
-        return {"success": bool(album.DeleteStills(to_delete))} if to_delete else _err("No valid still indices")
+        still_indices = p["still_indices"]
+        if not isinstance(still_indices, list) or not still_indices:
+            return _err("still_indices must be a non-empty list of 0-based indices")
+        # A negative index is a real Python index (`stills[-1]` is the last still),
+        # and an out-of-range one used to be dropped while the rest were deleted.
+        invalid = _invalid_indices(still_indices, len(stills))
+        if invalid:
+            return _err(f"still_indices out of range for {len(stills)} stills: {invalid}")
+        return {"success": bool(album.DeleteStills([stills[i] for i in still_indices]))}
     return _unknown(action, ["get_stills","get_label","set_label","import_stills","export_stills","grab_and_export","delete_stills"])
 
 

package/src/utils/multicam.py

@@ -99,6 +99,55 @@ def timecode_to_frames(timecode: Any, fps: Any, *, drop_frame: Optional[bool] =
     return total
 
 
+def frames_to_timecode(frame: Any, fps: Any, *, drop_frame: bool = False) -> Optional[str]:
+    """Convert a frame count back to HH:MM:SS:FF timecode.
+
+    The exact inverse of `timecode_to_frames`, and it lives next to it so the
+    pair cannot drift apart: a frames->timecode helper written on its own
+    reliably forgets that drop-frame dropped frame NUMBERS on the way in, and
+    then reports a timecode 3.6 seconds early per hour.
+
+    `drop_frame` renders drop-frame timecode (semicolon separator) at the two
+    nominal rates where it is defined, 30 and 60; at any other rate it is
+    ignored, exactly as `timecode_to_frames` ignores a semicolon there.
+    """
+    rate = parse_frame_rate(fps)
+    if rate is None:
+        return None
+    try:
+        frame = max(0, int(frame))
+    except (TypeError, ValueError):
+        return None
+    nominal = _nominal_timecode_rate(rate)
+    if nominal <= 0:
+        return None
+
+    if drop_frame and nominal in (30, 60):
+        # Two (30) or four (60) frame numbers are skipped at the top of every
+        # minute except every tenth, so a ten-minute block holds one full
+        # minute and nine short ones.
+        drop = 2 if nominal == 30 else 4
+        per_minute = nominal * 60 - drop
+        per_ten = per_minute * 10 + drop
+        tens, rem = divmod(frame, per_ten)
+        if rem < nominal * 60:
+            minutes = tens * 10
+            frame_in_minute = rem
+        else:
+            rem -= nominal * 60
+            extra_minutes, frame_in_minute = divmod(rem, per_minute)
+            minutes = tens * 10 + 1 + extra_minutes
+            frame_in_minute += drop
+        hours, minutes = divmod(minutes, 60)
+        seconds, frames = divmod(frame_in_minute, nominal)
+        return f"{hours:02d}:{minutes:02d}:{seconds:02d};{frames:02d}"
+
+    hours, remainder = divmod(frame, nominal * 3600)
+    minutes, remainder = divmod(remainder, nominal * 60)
+    seconds, frames = divmod(remainder, nominal)
+    return f"{hours:02d}:{minutes:02d}:{seconds:02d}:{frames:02d}"
+
+
 def _get_clip_property_map(clip: Any) -> Dict[str, Any]:
     try:
         props = clip.GetClipProperty()

package/src/utils/sync_detection.py

@@ -16,7 +16,7 @@ from array import array
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
 
-from src.utils.multicam import timecode_to_frames
+from src.utils.multicam import frames_to_timecode, timecode_to_frames
 
 
 SYNC_EVENT_TYPES = ("two_pop", "slate_clap")
@@ -237,38 +237,25 @@ def _probe_media(path: str, ffprobe_path: str, timeout: int) -> Dict[str, Any]:
     }
 
 
-def _nominal_timecode_rate(fps: float) -> int:
-    if abs(fps - 23.976) < 0.02:
-        return 24
-    if abs(fps - 29.97) < 0.02:
-        return 30
-    if abs(fps - 47.952) < 0.05:
-        return 48
-    if abs(fps - 59.94) < 0.05:
-        return 60
-    return int(round(fps))
-
-
-def _frames_to_timecode(frame: int, fps: float) -> Optional[str]:
-    if fps <= 0:
-        return None
-    nominal = _nominal_timecode_rate(fps)
-    if nominal <= 0:
-        return None
-    frame = max(0, int(frame))
-    hours, remainder = divmod(frame, nominal * 3600)
-    minutes, remainder = divmod(remainder, nominal * 60)
-    seconds, frames = divmod(remainder, nominal)
-    return f"{hours:02d}:{minutes:02d}:{seconds:02d}:{frames:02d}"
-
-
 def _timecode_for_event(time_seconds: float, fps: Optional[float], start_timecode: Optional[str]) -> Optional[str]:
+    """Timecode of an event `time_seconds` into a clip whose head is `start_timecode`.
+
+    The start timecode comes from the media's own timecode track, via ffprobe,
+    so on an NTSC deliverable it is routinely DROP-FRAME (`HH:MM:SS;FF`).
+    `timecode_to_frames` subtracts the dropped frame numbers on the way in, so
+    the way back out has to add them again — carry the drop-frame spelling
+    through rather than rendering the result as non-drop.
+    """
     if not fps or not start_timecode:
         return None
     start_frame = timecode_to_frames(start_timecode, fps)
     if start_frame is None:
         return None
-    return _frames_to_timecode(start_frame + int(round(time_seconds * fps)), fps)
+    return frames_to_timecode(
+        start_frame + int(round(time_seconds * fps)),
+        fps,
+        drop_frame=";" in str(start_timecode),
+    )
 
 
 def _event_marker_color(event_type: str, params: Dict[str, Any]) -> str: