davinci-resolve-mcp 2.159.0 → 2.161.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 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.161.0 — OTIO freeze frames close the loop
+
+### Fixed
+
+- **OTIO `FreezeFrame` effects were silently lost at parse**: the reader only
+  looked at `time_scalar`, which FreezeFrame writers commonly omit, so a
+  turnover freeze read as a plain 100% clip. The schema itself now means
+  speed 0, and the bridge authors the real freeze `Sm2TimeMap`.
+
+### Added
+
+- The OTIO writer emits `FreezeFrame.1` (time_scalar 0) for zero-speed
+  events — OTIO's own schema for it, readable by both conventions.
+
+### Measured
+
+- **Resolve's `EXPORT_OTIO` writes an authored freeze back as
+  `FreezeFrame.1` with `time_scalar: 0`** — the freeze round-trips
+  losslessly, and `verify_roundtrip` now catches a freeze flattened to 100%
+  as retime drift.
+
+## What's New in v2.160.0 — write-side span fidelity; the flat DRT target stops lying about black
+
+### Fixed
+
+- **`eventsToOTIO` forced every transition to centered**, so a start-at-cut
+  fade-in re-written to OTIO demanded incoming pre-roll the source never
+  needed — and the round-trip dropped the fade as handle starvation. The
+  writer now carries the source event's actual alignment (start-at-cut,
+  `inOffset`, or derived from `recStart`).
+- **The flat DRT target omitted nothing and authored a bogus `BL` offline
+  clip** for black legs. BL legs are now omitted — an empty track region
+  renders the same black without the media-offline lie — and the `drt`
+  result reports `blackLegsOmitted`.
+
 ## What's New in v2.159.0 — the EDL writer learns transitions
 
 ### Fixed

package/README.md

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

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.159.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.161.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-36%20(353%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)
 
-> 本翻译对应 v2.159.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.161.0 版 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 = "2.159.0"
+VERSION = "2.161.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.159.0",
+  "version": "2.161.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/server/author-interchange.mjs

@@ -152,17 +152,30 @@ export function eventsToOTIO(events, opts = {}) {
         },
         active_media_reference_key: 'DEFAULT_MEDIA',
       };
-      if ((e.speed ?? 100) !== 100 || e.reverse) {
+      if ((e.speed ?? 100) === 0) {
+        // Zero speed = freeze: OTIO's own schema for it (a LinearTimeWarp
+        // subclass with time_scalar 0), readable by both conventions (E103).
+        clip.effects.push({ OTIO_SCHEMA: 'FreezeFrame.1', name: 'Freeze', metadata: {}, effect_name: 'FreezeFrame', time_scalar: 0 });
+      } else if ((e.speed ?? 100) !== 100 || e.reverse) {
         clip.effects.push({ OTIO_SCHEMA: 'LinearTimeWarp.1', name: 'Speed', metadata: {}, effect_name: 'LinearTimeWarp', time_scalar: (e.reverse ? -1 : 1) * ((e.speed ?? 100) / 100) });
       }
       if (e.transition) {
+        // Span fidelity (E102): carry the source event's actual alignment
+        // instead of forcing centered — a centered rewrite of a start-at-cut
+        // fade-in demands incoming pre-roll the source never needed, and the
+        // conform then drops it as handle starvation.
+        const d = e.transition.duration || 0;
+        let inOff = Math.ceil(d / 2);
+        if (e.transition.alignment === 'start') inOff = 0;
+        else if (e.transition.inOffset != null) inOff = Math.max(0, Math.min(d, e.transition.inOffset));
+        else if (e.transition.recStart != null && e.recIn != null) inOff = Math.max(0, Math.min(d, e.recIn - e.transition.recStart));
         children.push({
           OTIO_SCHEMA: 'Transition.1',
           metadata: {},
           name: 'Cross Dissolve',
           transition_type: 'SMPTE_Dissolve',
-          in_offset: rt(Math.ceil((e.transition.duration || 0) / 2), fps),
-          out_offset: rt(Math.floor((e.transition.duration || 0) / 2), fps),
+          in_offset: rt(inOff, fps),
+          out_offset: rt(d - inOff, fps),
         });
       }
       children.push(clip);
@@ -780,7 +793,13 @@ export function drtFlattenedRetimes(events) {
 /** Build a buildDRT spec (Resolve-native .drt) from normalized events. */
 export function eventsToDrtSpec(events, opts = {}) {
   const fps = opts.fps || events.find((e) => e.fps)?.fps || 24;
-  const groups = byTrack(events);
+  // BL legs are OMITTED on this flat target (E102): a 'BL' mediaFilePath
+  // would author a bogus offline clip, while an empty track region renders
+  // black anyway — the same picture without the media-offline lie. (The
+  // fade transitions themselves flatten on DRT by design; use
+  // drt.assemble_from_interchange for a .drt that AUTHORS them.)
+  const isBLev = (e) => /^(BL|BLACK)$/i.test(String(e.source || '').trim());
+  const groups = byTrack(events.filter((e) => !isBLev(e)));
   const mkTrack = (list) => ({
     clips: list.map((e) => ({ start: e.recIn ?? 0, duration: (e.recOut ?? 0) - (e.recIn ?? 0), in: e.srcIn ?? 0, mediaFilePath: e.source || '' })),
   });
@@ -817,7 +836,11 @@ export async function authorInterchange(events, target, opts = {}) {
   if (t === 'drt') {
     const spec = eventsToDrtSpec(events, opts);
     const buf = await drt().buildDRT(spec);
-    return { target: 'drt', spec, buffer: buf, bytes: buf.length, flattened: drtFlattenedRetimes(events) };
+    const blackLegsOmitted = events.filter((e) => /^(BL|BLACK)$/i.test(String(e.source || '').trim())).length;
+    return {
+      target: 'drt', spec, buffer: buf, bytes: buf.length, flattened: drtFlattenedRetimes(events),
+      ...(blackLegsOmitted ? { blackLegsOmitted } : {}),
+    };
   }
   throw new Error(`authorInterchange: unknown target '${target}' (otio|edl|drt)`);
 }

package/resolve-advanced/server/editorial.mjs

@@ -216,6 +216,13 @@ export function parseOTIO(otio, opts = {}) {
             speed = +(eff.time_scalar * 100).toFixed(2);
             reverse = eff.time_scalar < 0;
           }
+          // OTIO FreezeFrame is a LinearTimeWarp subclass whose time_scalar
+          // is 0 by definition — writers commonly omit the field, which
+          // read as a plain 100% clip here (E103). Speed 0 authors a freeze.
+          if (/^FreezeFrame\b/.test(String(eff.OTIO_SCHEMA || ''))) {
+            speed = 0;
+            reverse = false;
+          }
         }
         const src = (child.media_reference && (child.media_reference.target_url || child.media_reference.name)) || child.name || 'UNKNOWN';
         // CLIP markers belong to the ITEM, not the sequence — carried as

package/resolve-advanced/server/tools/editorial.mjs

@@ -86,7 +86,7 @@ const markerSchema = z.object({
 export const editorialTool = {
   name: 'editorial',
   description:
-    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively + AAF via pyaaf2 + PRPROJ via gunzip+XML → normalized events incl. span-explicit transitions and BL fade legs; for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source; the EDL target writes CMX transition pairs incl. BL fades — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → moved/retimed/replaced/new/gone + timing flags), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base; BL-aware — black legs need no source, fades no black-side handles, and a fade-out tail requirement lands on the picture source), marker_roundtrip (markers with provenance tags), verify_roundtrip (input events vs re-export events -> pass/mismatches + fitted per-source TC offsets + marker compare w/ markersNotInExport honesty flag; FADE-AWARE: BL/Solid-Color legs merge out as blackSegments and fade-window boundary reshapes are excused into fadeReshapedBoundaries instead of failing; RETIME-AWARE: speed/reverse compare pairwise — EXPORT_OTIO carries an authored Sm2TimeMap back as LinearTimeWarp (measured), so a flattened/lost retime fails as drift geometry alone cannot catch; AUDIO-AWARE: declared audio events compare (channel legs deduped, mismatches tagged trackType audio) while the mirrored-A1 export of a video-only turnover stays informational; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
+    'Editorial integrity (Cluster E) — turnover interchange → normalized events → changelist + conform manifest with TIMING silent-lie guards (flattened retime / dropped J/L-cut audio / framerate-pulldown slip / reverse dropped / transition-handle starvation → flag, skip-not-fake). Report-only (gate: review). Actions: parse_interchange (EDL/OTIO/XMEML natively + AAF via pyaaf2 + PRPROJ via gunzip+XML → normalized events incl. span-explicit transitions, BL fade legs, and OTIO FreezeFrame effects as zero-speed freezes; for AAF/PRPROJ pass the file PATH as content; AAF also returns per-sequence startTimecode/startFrame — build the timeline at THAT start, not the Resolve 01:00:00:00 default — and per-clip `geometry` for Avid transform effects), list_sequences (ONE offline picker entry point across xml/edl/otio/drt/drp/aaf/prproj → [{id,name,eventCount}], plus startTimecode/startFrame for AAF), convert_to_interchange (author OTIO/EDL/DRT Resolve CAN import from events or a parsed source; the EDL target writes CMX transition pairs incl. BL fades — the .prproj→Resolve conform bridge, no Premiere needed; editorial timing/transitions survive and per-clip effects/color do not. SPEED/REVERSE survive on the otio (LinearTimeWarp) and edl (M2) targets ONLY — this FLAT drt target flattens every retime to 100% forward and returns `flattened`/`flattenedCount` naming each event that lost one (`flattened` is always present on `drt`, empty when there were none); for a .drt that AUTHORS retimes/dissolves/multi-track/audio, use drt.assemble_from_interchange), turnover_changelist (diff old vs new → moved/retimed/replaced/new/gone + timing flags), conform_manifest (per-event assert: source resolved/handles/retime/reverse/TC-base; BL-aware — black legs need no source, fades no black-side handles, and a fade-out tail requirement lands on the picture source), marker_roundtrip (markers with provenance tags), verify_roundtrip (input events vs re-export events -> pass/mismatches + fitted per-source TC offsets + marker compare w/ markersNotInExport honesty flag; FADE-AWARE: BL/Solid-Color legs merge out as blackSegments and fade-window boundary reshapes are excused into fadeReshapedBoundaries instead of failing; RETIME-AWARE: speed/reverse compare pairwise — EXPORT_OTIO carries an authored Sm2TimeMap back as LinearTimeWarp (measured), so a flattened/lost retime fails as drift geometry alone cannot catch; AUDIO-AWARE: declared audio events compare (channel legs deduped, mismatches tagged trackType audio) while the mirrored-A1 export of a video-only turnover stays informational; the conform QC loop-closer). Offline (AAF needs pyaaf2; live AAF/DRP import is on the Python davinci-resolve MCP).',
   async handler({ action, args }) {
     if (action === 'parse_interchange') {
       const p = parseSchema.parse(args);

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.159.0"
+VERSION = "2.161.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/server.py

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