davinci-resolve-mcp 4.7.9 → 4.7.10

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.7.9-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.9-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.9 版 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.9"
+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.9",
+  "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.9"
+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()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "4.7.9"
+VERSION = "4.7.10"
 
 import base64
 import os

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: