davinci-resolve-mcp 2.156.0 → 2.156.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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.156.1 — docs catch up with the fade + QC arc
+
+### Documentation
+
+- `docs/guides/native-drt-authoring.md` learns the v2.148–2.156 arc: the
+  A1–A16 audio ceiling, the fade capability row and the fade/AAF-overlap
+  laws, the `blackLegs` ledger field, and the full `verify_roundtrip`
+  surface (markers, fades, retimes, audio) in the delivery checklist.
+- The Native .drt Authoring and Headless Edit Loop guides are now linked
+  from both READMEs' guide tables — both were orphaned.
+
 ## What's New in v2.156.0 — the QC loop learns audio; the verify surface is complete
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.156.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.156.1-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)
@@ -303,6 +303,8 @@ For method-by-method status, see [API Coverage and Test Results](docs/reference/
 | [Multicam Setup Helper Guide](docs/guides/multicam-setup-guide.md) | Stacked timeline prep, helper/API boundary, and Resolve UI conversion steps |
 | [Editorial Decision Guide](docs/guides/editorial-decision-guide.md) | Project-owned editorial craft guidance for analysis and timeline decisions |
 | [Conforming an Avid AAF](docs/guides/conforming-an-avid-aaf.md) | Why all three Resolve-native routes fail on a consolidated turnover, and which one is dangerous |
+| [Native .drt Authoring](docs/guides/native-drt-authoring.md) | Offline template-spliced timeline authoring: cuts, retimes, transitions, fades, markers, compounds — and the measured laws behind them |
+| [Headless Edit Loop](docs/guides/headless-edit-loop.md) | Driving Resolve from the command line: which interchange formats relink and round-trip, measured in GUI and -nogui |
 | [Color Decision Guide](docs/guides/color-decision-guide.md) | Project-owned color correction guidance and Resolve color API boundaries |
 | [Contributing and Project Layout](docs/contributing.md) | Contribution workflow, platform support, security notes, repository structure |
 | [Security Policy](SECURITY.md) | Local stdio trust boundary, tool metadata, confirmation guidance, reporting |

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.156.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.156.1-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.156.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.156.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -221,6 +221,8 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 | [多机位设置助手指南](docs/guides/multicam-setup-guide.md) | 堆叠时间线准备、助手/API 边界、Resolve UI 转换步骤 |
 | [剪辑决策指南](docs/guides/editorial-decision-guide.md) | 项目自有的剪辑手艺指引，用于分析与时间线决策 |
 | [套底 Avid AAF](docs/guides/conforming-an-avid-aaf.md) | 为何三条 Resolve 原生路径在合并交接上全部失败，以及哪条最危险 |
+| [原生 .drt 离线创作](docs/guides/native-drt-authoring.md) | 离线模板拼接式时间线创作：剪切、变速、转场、淡入淡出、标记、复合片段，以及背后的实测规律 |
+| [无界面剪辑循环](docs/guides/headless-edit-loop.md) | 纯命令行驱动 Resolve：哪些交换格式能重新链接并往返，GUI 与 -nogui 双双实测 |
 | [调色决策指南](docs/guides/color-decision-guide.md) | 项目自有的校色指引与 Resolve 调色 API 边界 |
 | [贡献与项目布局](docs/contributing.md) | 贡献流程、平台支持、安全说明、仓库结构 |
 | [安全策略](SECURITY.md) | 本地 stdio 信任边界、工具元数据、确认指引、漏洞报告 |

package/docs/guides/native-drt-authoring.md

@@ -45,6 +45,7 @@ window. `render.verify_output` covers the container-level checks.
 | Wipes (EDL `W`-codes) | `transitions[].type: 'wipe'` (single soft-edge style — host-importer parity) | v2.138 |
 | Transition styles | `transitions[].type: 'dip' \| 'additive' \| 'fade-to-color' \| 'smooth-cut' \| 'non-additive'` (XMEML effectids route automatically) | v2.140 |
 | Audio cross-fades | `transitions[].trackType: 'audio'` | v2.116 |
+| Fades to/from black | EDL `BL` dissolves, OTIO gap-adjacent Transitions, XMEML/PrProj edge spans, AAF filler-adjacent Transitions — authored as Solid-Color-generator dissolves | v2.150–2.155 |
 | Constant retimes, forward | `cuts[].speed` (e.g. `0.5`) | v2.113 |
 | Constant retimes, reverse | `cuts[].reverse` | v2.114 |
 | Freeze frames | `cuts[].freeze` (holds source frame `srcIn`) | v2.134 |
@@ -70,7 +71,8 @@ plus a `sourceMap` — all five formats are route-proven end-to-end
 (parse → assemble → import → measured frames and RMS) — and
 returns an honesty ledger
 (`authoredTransitions`, `droppedTransitions` with reasons, `authoredRetimes`,
-`flattenedRetimes`, `authoredAudioEvents`, `upperTrackCutsVideoOnly`).
+`flattenedRetimes`, `authoredAudioEvents`, `upperTrackCutsVideoOnly`,
+`blackLegs` for authored fade generators and skipped audio-silence legs).
 
 ## The laws (why the constraints are what they are)
 
@@ -153,6 +155,24 @@ for the post-cut portion. Off-center spans render (blend measured across an
 uneven [cut-6, cut+18) span); everything unauthorable stays in
 `droppedTransitions` with the reason.
 
+**Fade law.** A transition needs a physical item on BOTH sides of its
+junction: a hand-authored single-sided transition element (span at a lone
+clip head or tail) refuses to import entirely, and Resolve's own EDL
+importer silently DROPS dissolves involving the `BL` reel (the fade-in
+vanishes; the fade-out hard-cuts into the Solid Color it creates). The
+authorable form — used automatically by `assemble_from_interchange` for all
+five formats — is a real clip↔Solid-Color-generator dissolve: a zero-length
+black leg materializes/grows to cover its side of the span (empty track
+renders black, so the growth is render-neutral), and the CMX zero-length
+fade-in slug grows through the boundary shift. Audio fades to silence have
+no authorable form (no silence source) and drop with the stated reason.
+
+**AAF overlap law.** An AAF Transition CONSUMES record time: the incoming
+component legitimately overlaps the outgoing by the transition duration.
+The bridge trims the outgoing's tail to the overlap start and lets the
+boundary shift re-extend it to the `CutPoint` — the AAF notional-cut
+semantics exactly.
+
 ## Verification checklist for a delivered .drt
 
 1. `timeline.import_timeline_checked` — expect `linked == total` for media
@@ -170,7 +190,15 @@ uneven [cut-6, cut+18) span); everything unauthorable stays in
    verifier normalizes track labels, source naming, and per-source
    TC-absolute source frames (fitting the offsets, e.g. 86400 for a
    01:00:00:00 source) — `pass: true` means the authored timeline's export
-   matches the turnover's intent event-for-event.
+   matches the turnover's intent event-for-event. The verify surface covers
+   the whole authored family: timeline markers (`markersNotInExport` flags a
+   marker-less export instead of failing — EXPORT_OTIO drops them), fades
+   (BL/Solid-Color legs merge out as `blackSegments`; fade-window boundary
+   reshapes are excused into `fadeReshapedBoundaries`, never silently),
+   retimes (speed/reverse compare pairwise — EXPORT_OTIO round-trips an
+   authored Sm2TimeMap as LinearTimeWarp), and audio (declared audio events
+   compare with `trackType: 'audio'` tags; the A1 convenience mirror on a
+   video-only turnover stays informational).
 
 ## References
 

package/install.py

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

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.156.0"
+VERSION = "2.156.1"
 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.156.0"
+VERSION = "2.156.1"
 
 import base64
 import os