davinci-resolve-mcp 2.148.0 → 2.150.0

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 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.150.0 — fades conform: BL legs author, and Resolve's own EDL importer drops them
+
+### Added
+
+- **EDL fades author end-to-end** in `drt.assemble_from_interchange`: BL
+  (black) legs become Solid Color generator elements and the fades real
+  clip-to-generator dissolves. A CMX fade-in's zero-length BL slug grows
+  through the boundary-shift machinery (single-sided transitions refuse to
+  import — measured); the picture trims its head with source staying
+  record-aligned. Render-proven: luma ramps 18→123 across a 24-frame
+  fade-in and 123→16 across the fade-out, with the black tail holding.
+  Audio BL fades (to silence) drop with a stated reason — there is no
+  silence source to cross-fade against.
+- Generator elements now insert into the track in **chronological item
+  order** (junction detection reads listed adjacency), and an edge-aligned
+  span whose leg is shorter than its boundary shift drops with a reason
+  instead of authoring a broken geometry.
+
+### Measured (new Resolve bug, filed in api-limitations)
+
+- **Resolve's own EDL importer silently drops BL dissolves**: the fade-in
+  vanishes wholesale (frame 0 renders full-bright) and a fade-out leaves a
+  hard cut into the Solid Color generator it creates for the BL slug. A
+  single-sided transition element refuses to import entirely.
+
+## What's New in v2.149.0 — subtitle render truth: ExportSubtitle lies on 19.x
+
+### Measured (new Resolve bug, filed in api-limitations)
+
+- **`SetRenderSettings` subtitle keys are accepted-and-inert on 19.x**: with
+  authored subtitle cues readback-verified and the track enabled,
+  `ExportSubtitle: true` + every `SubtitleFormat` mode (`BurnIn`,
+  `SeparateFile`, `EmbeddedCaptions`) returns True — and the renders carry no
+  burned-in pixels, no sidecar file, and no caption stream. The keys are
+  documented in the Resolve 21 API reference. Quirk: `ExportSubtitle` alone
+  returns False; the pair returns True.
+
+### Added
+
+- **`render.set_settings` warns on pre-21 hosts** when the subtitle-delivery
+  keys are set, naming the measured inertness and the verification steps —
+  the accepted-then-ignored warning pattern that already covers
+  `AddFrameHandles` under `UseFullExtents`.
+
 ## What's New in v2.148.0 — the audio ceiling doubles: A1–A16
 
 ### Changed

package/README.md

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

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 35 missing capabilities, 48 bugs / unreliable behaviors.
+**Totals:** 35 missing capabilities, 50 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -687,3 +687,19 @@ values, or automation-hostile modal prompts.
 - **Behavior:** Timeline markers present and readable through the marker API do not appear in the exported .otio at all — the OTIO Marker schema exists and Resolve's importer reads it, but the exporter writes none (measured on Studio 19.1.3.7: two markers read back at frames 12/72; the export carried zero). Any marker-fidelity QC built on an OTIO re-export silently sees an unmarked timeline.
 - **Workaround / current handling:** Do not use EXPORT_OTIO to carry or verify markers. editorial.verify_roundtrip reports this case as `markersNotInExport` (honesty flag, not a failure); read markers through the marker API for fidelity checks, and author them offline via drt.assemble spec.markers when a .drt must carry them.
 - **Tags:** timeline, export, otio, markers, silent-failure
+
+### MediaPool.ImportTimelineFromFile EDL (drops BL fades)
+
+- **Object:** `MediaPool`
+- **Signature:** `(filePath.edl, importOptions) -> Timeline`
+- **Behavior:** EDL dissolves involving the BL (black) reel are dropped silently on import (measured on Studio 19.1.3.7, E91): a CMX fade-in (zero-length BL cut + D event) vanishes wholesale — frame 0 renders at full brightness — and a fade-out to a BL leg imports the BL as a Solid Color generator but drops the dissolve, leaving a hard cut to black. Import succeeds; the importer authors dissolves normally between two real media clips. A related law: a hand-authored SINGLE-SIDED transition element (span at a lone clip head or tail, only one neighboring item) refuses to import entirely — Resolve creates no timeline.
+- **Workaround / current handling:** Conform EDLs with fades through drt.assemble_from_interchange: BL legs author as Solid Color generator elements and the fades as real clip-to-generator dissolves (render-verified: luma ramps 18->123 across a 24f fade-in and 123->16 across the fade-out, black tail holding 16). Audio BL fades (to silence) drop with a stated reason — there is no silence source to cross-fade against.
+- **Tags:** edl, import, transitions, fades, silent-failure
+
+### Project.SetRenderSettings ExportSubtitle/SubtitleFormat (inert on 19.x)
+
+- **Object:** `Project`
+- **Signature:** `({'ExportSubtitle': bool, 'SubtitleFormat': str}) -> bool`
+- **Behavior:** On Studio 19.1.3.7 the subtitle-delivery keys documented in the Resolve 21 API reference are accepted and fully inert: SetRenderSettings returns True for all three SubtitleFormat modes ('BurnIn', 'SeparateFile', 'EmbeddedCaptions'), and the renders carry no burned-in pixels (frame-extract verified), no sidecar subtitle file, and no embedded caption track (stream-probe verified) — with the subtitle cues readback-verified on the timeline and the subtitle track enabled. Quirk: ExportSubtitle alone returns False; the pair returns True. All three outputs are stream-identical to a no-subtitle render.
+- **Workaround / current handling:** Do not trust a True return for subtitle delivery on a pre-21 host — verify the output (extract a frame for burn-in, list the target directory for a sidecar, ffprobe streams for embedded captions). On 19.x subtitle export requires the UI render page. render.set_settings warns when these keys are set on a pre-21 host.
+- **Tags:** render, subtitle, burn-in, silent-failure, version-gated

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.148.0"
+VERSION = "2.150.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.148.0",
+  "version": "2.150.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

@@ -258,7 +258,13 @@ export function eventsToAssembleSpec(events, opts = {}) {
   const audioSkipped = events.length - vids.length - audsRaw.length - markerEvents.length;
   if (!vids.length) throw new Error('eventsToAssembleSpec: no video events with record ranges');
 
-  const unmapped = [...new Set([...vids, ...auds].map((e) => e.source).filter((srcName) => !sourceMap[srcName]))];
+  // BL/BLACK reels are the EDL's built-in black source — they never need a
+  // sourceMap entry. Video BL legs author as Solid Color generator elements
+  // (Resolve's own EDL importer creates exactly that for the slug — but DROPS
+  // the fade dissolves around it, measured E91); audio BL legs are silence,
+  // which an empty track already is.
+  const isBL = (srcName) => /^(BL|BLACK)$/i.test(String(srcName || '').trim());
+  const unmapped = [...new Set([...vids, ...auds].map((e) => e.source).filter((srcName) => !isBL(srcName) && !sourceMap[srcName]))];
   if (unmapped.length) {
     throw new Error(
       `eventsToAssembleSpec: unmapped source reel(s): ${unmapped.join(', ')} — ` +
@@ -285,12 +291,40 @@ export function eventsToAssembleSpec(events, opts = {}) {
   const minRec = preserveStartTimecode ? 0 : minRecRaw;
   const ORIGIN = preserveStartTimecode ? 0 : DEFAULT_ORIGIN;
   const startFrame = preserveStartTimecode ? minRecRaw : DEFAULT_ORIGIN;
+  const blackLegs = [];
   for (const e of vids) {
     const recIn = ORIGIN + (toTl(e.recIn, e.fps) - minRec);
     const recOut = ORIGIN + (toTl(e.recOut, e.fps) - minRec);
     const durationFrames = recOut - recIn;
+    const vTrackEarly = trackNum(e.track);
+    if (isBL(e.source)) {
+      // BL leg → Solid Color generator element (renders black; the authored
+      // clip↔generator dissolve render-verified E91: luma ramps 124→16
+      // through the junction). ZERO-length BL is kept as a placement so a
+      // fade-in's boundary-shift can GROW it — the CMX fade-in form is a
+      // zero-length BL cut followed by a D event, and a single-sided
+      // transition refuses to import (measured E91), so the shift is the
+      // only authorable shape.
+      if (durationFrames < 0) continue;
+      const el = { type: 'generator', generatorName: 'Solid Color', track: vTrackEarly, startFrame: recIn, durationFrames, srcIn: 0 };
+      blackLegs.push(el);
+      if (e.transition) {
+        let d = Math.max(2, toTl(e.transition.duration || 0, e.fps) || 2);
+        d += d % 2;
+        let pre = Math.floor(d / 2);
+        if (e.transition.alignment === 'start') pre = 0;
+        transitionCandidates.push({
+          atFrame: recIn, durationFrames: d, track: vTrackEarly, pre,
+          explicitSpan: e.transition.alignment != null,
+          index: e.index, type: e.transition.type, rawDuration: e.transition.duration,
+          source: e.source, srcIn: Infinity, incomingCutRef: el, cutPoint: e.transition.cutPoint,
+        });
+      }
+      placements.push({ start: recIn, end: recOut, index: e.index, source: e.source, srcIn: Infinity, durationFrames, track: vTrackEarly, cutRef: el });
+      continue;
+    }
     if (durationFrames <= 0) continue;
-    const vTrack = trackNum(e.track);
+    const vTrack = vTrackEarly;
     const cut = { startFrame: recIn, durationFrames, srcIn: toTl(e.srcIn ?? 0, e.fps), ...(vTrack > 1 ? { track: vTrack } : {}) };
     // CLIP markers from the turnover (OTIO clip markers, XMEML clipitem
     // <marker>s) become ITEM markers on the cut (frames clip-relative,
@@ -363,7 +397,21 @@ export function eventsToAssembleSpec(events, opts = {}) {
   const audioPlacements = [];
   const audioRetimesSkipped = [];
   const audioTransCandidates = [];
+  let audioBlackLegsSkipped = 0;
   for (const e of auds) {
+    if (isBL(e.source)) {
+      // Audio BL = silence, which an empty track already is. A fade to/from
+      // it has no authorable form (no silence source to cross-fade against);
+      // the level steps at the cut instead of ramping — stated, not silent.
+      audioBlackLegsSkipped += 1;
+      if (e.transition) {
+        droppedTransitions.push({
+          index: e.index, type: e.transition.type, duration: e.transition.duration, trackType: 'audio',
+          reason: 'audio fade to/from BL (silence) — no silence source to cross-fade against; the level steps at the cut',
+        });
+      }
+      continue;
+    }
     const recIn = ORIGIN + (toTl(e.recIn, e.fps) - minRec);
     const recOut = ORIGIN + (toTl(e.recOut, e.fps) - minRec);
     const durationFrames = recOut - recIn;
@@ -408,7 +456,10 @@ export function eventsToAssembleSpec(events, opts = {}) {
 
   // Overlap is judged PER VIDEO TRACK — V2 stacking over V1 is legitimate
   // conform geometry (render-verified: an upper-track clip covers the lower).
-  placements.sort((a, b) => a.start - b.start);
+  // end-tiebreak keeps a zero-length BL placement AHEAD of the picture leg
+  // that starts at the same frame (fade-in form) — start-only sorting would
+  // read them as an overlap.
+  placements.sort((a, b) => a.start - b.start || a.end - b.end);
   const byTrack = new Map();
   for (const pl of placements) {
     if (!byTrack.has(pl.track)) byTrack.set(pl.track, []);
@@ -457,10 +508,14 @@ export function eventsToAssembleSpec(events, opts = {}) {
     // FULL-duration outgoing tail.
     const pre = c.pre ?? c.durationFrames / 2;
     const post = c.durationFrames - pre;
+    // A BL side has infinite handles: a Solid Color generator extends freely
+    // in both directions (srcIn is already Infinity on BL candidates).
     const bHandle = c.srcIn >= pre;
     const aSpec = sourceMap[prev.source] && sourceMap[prev.source].spec;
     const aFrames = aSpec && Number(aSpec.frameCount);
-    const aHandle = Number.isFinite(aFrames) ? prev.srcIn + prev.durationFrames + post <= aFrames : false;
+    const aHandle = isBL(prev.source)
+      ? true
+      : (Number.isFinite(aFrames) ? prev.srcIn + prev.durationFrames + post <= aFrames : false);
     if (!bHandle || !aHandle) {
       droppedTransitions.push({
         index: c.index, type: c.type, duration: c.rawDuration,
@@ -496,6 +551,16 @@ export function eventsToAssembleSpec(events, opts = {}) {
       // span, the edge law), else center.
       const cp = Number.isInteger(c.cutPoint) ? Math.min(c.durationFrames - 1, Math.max(1, c.cutPoint)) : c.durationFrames / 2;
       const shift = (pre === 0 ? 1 : -1) * cp;
+      // The shift must leave BOTH legs with positive duration — a leg
+      // shorter than the boundary shift cannot host its half of the span
+      // (and a zero-length survivor would re-create the inert edge form).
+      if (c.incomingCutRef.durationFrames - shift <= 0 || prev.cutRef.durationFrames + shift <= 0) {
+        droppedTransitions.push({
+          index: c.index, type: c.type, duration: c.rawDuration,
+          reason: `a leg is shorter than the ${Math.abs(shift)}f boundary shift the edge-aligned span requires`,
+        });
+        continue;
+      }
       prev.cutRef.durationFrames += shift;
       c.incomingCutRef.startFrame += shift;
       c.incomingCutRef.srcIn += shift;
@@ -563,8 +628,15 @@ export function eventsToAssembleSpec(events, opts = {}) {
     }))
     .filter((m) => m.frame >= (preserveStartTimecode ? startFrame : DEFAULT_ORIGIN));
 
+  // BL legs with surviving extent (a fade-in's zero-length slug GROWS through
+  // the boundary shift; one that never met a dissolve stays zero and drops
+  // out). srcIn was only scaffolding for the shift math — strip it.
+  const elements = blackLegs
+    .filter((el) => el.durationFrames > 0)
+    .map(({ srcIn: _srcIn, ...rest }) => rest);
+
   return {
-    spec: { timelineName, media, ...(preserveStartTimecode ? { startFrame } : {}), ...(markers.length ? { markers } : {}), ...(transitions.length ? { transitions } : {}) },
+    spec: { timelineName, media, ...(preserveStartTimecode ? { startFrame } : {}), ...(markers.length ? { markers } : {}), ...(transitions.length ? { transitions } : {}), ...(elements.length ? { elements } : {}) },
     report: {
       videoEvents: vids.length,
       sources: media.length,
@@ -573,7 +645,10 @@ export function eventsToAssembleSpec(events, opts = {}) {
       audioChannelLegsMerged,
       authoredAudioEvents: audioPlacements.length,
       audioRetimesSkipped,
-      upperTrackCutsVideoOnly: placements.filter((pl) => pl.track > 1).length,
+      ...(elements.length || audioBlackLegsSkipped ? {
+        blackLegs: { authoredGenerators: elements.length, audioSilenceLegsSkipped: audioBlackLegsSkipped },
+      } : {}),
+      upperTrackCutsVideoOnly: placements.filter((pl) => pl.track > 1 && !isBL(pl.source)).length,
       flattenedRetimes,
       authoredRetimes,
       authoredTransitions: transitions,

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

@@ -153,7 +153,7 @@ function requirePathArg(args, key, action) {
 export const drtTool = {
   name: 'drt',
   description:
-    'DaVinci Resolve Timeline (.drt) operations — offline, no Resolve required. Actions: assemble_from_interchange (EDL/OTIO/XML/AAF + sourceMap → IMPORTABLE RENDERING native .drt in one call; retimes AUTHOR — constant speed fwd/rev AND zero-speed freezes (EDL M2 000.0; render-proven frozen); cross-dissolves are AUTHORED when the cut abuts with handles both sides (render-verified on 19), else dropped with reason; ledger in `conform`), assemble (spec → IMPORTABLE native-schema .drt via template-spliced real structures; pass targetAppVersion e.g. \'19.1\' for pre-21 hosts), parse, list_sequences (enumerate the timelines inside a .drp/.drt → [{id,name,eventCount,index}] to drive a "which sequence?" picker), author, validate, inject_into_drp, extract_from_drp (pull one SeqContainer out as a .drt — feed the .drt to the Python davinci-resolve MCP timeline.import_timeline_checked, or use timeline.import_from_drp to do both), downgrade (stamp <ProjectVersion> down so an OLDER Resolve will import a .drt/.drp from a newer one — pass targetAppVersion like "19.1.3" or targetProjectVersion).',
+    'DaVinci Resolve Timeline (.drt) operations — offline, no Resolve required. Actions: assemble_from_interchange (EDL/OTIO/XML/AAF + sourceMap → IMPORTABLE RENDERING native .drt in one call; retimes AUTHOR — constant speed fwd/rev AND zero-speed freezes (EDL M2 000.0; render-proven frozen); cross-dissolves are AUTHORED when the cut abuts with handles both sides (render-verified on 19), else dropped with reason; EDL BL fades AUTHOR too — BL legs become Solid Color generators and the fade a real clip-to-generator dissolve, luma-ramp render-verified, while Resolve\'s OWN EDL importer drops BL dissolves silently; ledger in `conform`), assemble (spec → IMPORTABLE native-schema .drt via template-spliced real structures; pass targetAppVersion e.g. \'19.1\' for pre-21 hosts), parse, list_sequences (enumerate the timelines inside a .drp/.drt → [{id,name,eventCount,index}] to drive a "which sequence?" picker), author, validate, inject_into_drp, extract_from_drp (pull one SeqContainer out as a .drt — feed the .drt to the Python davinci-resolve MCP timeline.import_timeline_checked, or use timeline.import_from_drp to do both), downgrade (stamp <ProjectVersion> down so an OLDER Resolve will import a .drt/.drp from a newer one — pass targetAppVersion like "19.1.3" or targetProjectVersion).',
   async handler({ action, args }) {
     if (action === 'parse') {
       const p = parseSchema.parse(requirePathArg(args, 'drtPath', 'parse'));

package/resolve-advanced/vendor/drp-format/place-generator.js

@@ -27,6 +27,8 @@ const {
   insertClipIntoTrack,
   replaceTrackVec,
   getTrackVec,
+  getItemsInner,
+  setItemsInner,
   freshDbIds,
 } = require('./seq-surgery');
 
@@ -72,7 +74,23 @@ async function placeGenerator(drpInput, opts = {}) {
   let createdTracks = 0;
   const cloneSource = tracks[0];
   while (tracks.length < trackIndex) { tracks.push(emptyTrackClone(cloneSource)); createdTracks += 1; }
-  tracks[trackIndex - 1] = insertClipIntoTrack(tracks[trackIndex - 1], gen);
+  // Insert in CHRONOLOGICAL item order, not appended: placeTransition detects
+  // junctions by listed adjacency, so a generator that precedes a clip in
+  // time (a fade-in's black slug, E91) must precede it in <Items> too.
+  // Compound-clip elements are not scanned (their nested inner <Element>s
+  // defeat the lazy regex); a generator meant to sit before one appends.
+  const track = tracks[trackIndex - 1];
+  const innerItems = getItemsInner(track);
+  const clipRe = /<Element>\s*<Sm2Ti(?:VideoClip|AudioClip|Generator)\b[\s\S]*?<\/Sm2Ti(?:VideoClip|AudioClip|Generator)>\s*<\/Element>/g;
+  let insertAt = -1;
+  let m;
+  while ((m = clipRe.exec(innerItems)) !== null) {
+    const sm = /<Start>(\d+)<\/Start>/.exec(m[0]);
+    if (sm && parseInt(sm[1], 10) > startFrame) { insertAt = m.index; break; }
+  }
+  tracks[trackIndex - 1] = insertAt >= 0
+    ? setItemsInner(track, innerItems.slice(0, insertAt) + gen + innerItems.slice(insertAt))
+    : insertClipIntoTrack(track, gen);
 
   const xml = replaceTrackVec(seqXml, 'video', vtv, tracks);
   zip.file(entry, xml);

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.148.0"
+VERSION = "2.150.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.148.0"
+VERSION = "2.150.0"
 
 import base64
 import os
@@ -18730,7 +18730,7 @@ def _render_preset_pin(proj, preset_name: str):
     return {"preset": preset_name, "loaded": True}, None
 
 
-def _render_settings_warnings(settings: Dict[str, Any]):
+def _render_settings_warnings(settings: Dict[str, Any], version_major: Optional[int] = None):
     """Inter-key combinations Resolve accepts and then silently ignores.
 
     SetRenderSettings returns True for these, so nothing downstream would ever
@@ -18745,6 +18745,17 @@ def _render_settings_warnings(settings: Dict[str, Any]):
             "AddFrameHandles is ignored while UseFullExtents is true: Resolve renders the "
             "clip's full extents and the handle count silently does nothing. Drop one of the two."
         )
+    if ("ExportSubtitle" in settings or "SubtitleFormat" in settings) and (
+        version_major is not None and version_major < 21
+    ):
+        warnings.append(
+            "ExportSubtitle/SubtitleFormat are INERT on this Resolve generation: measured on "
+            "Studio 19.1.3.7, SetRenderSettings returns True for all three SubtitleFormat modes "
+            "and the render carries no burn-in, no sidecar file, and no embedded caption track "
+            "(cues readback-verified, subtitle track enabled). The keys are documented in the "
+            "Resolve 21 API reference. Verify the output (frame extract / sidecar check) before "
+            "claiming caption delivery; on 19.x burn-in requires the UI render page."
+        )
     return warnings
 
 
@@ -19283,6 +19294,12 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         "Same as project", or "None"). AddFrameHandles is ignored while
         UseFullExtents is true — the call still succeeds, so that pairing
         comes back in warnings rather than silently doing nothing.
+        ExportSubtitle (bool) + SubtitleFormat ("BurnIn" | "SeparateFile" |
+        "EmbeddedCaptions") are documented for Resolve 21 but measured INERT
+        on 19.x — SetRenderSettings returns True and the render carries no
+        burn-in, sidecar, or caption track — so setting them on a pre-21
+        host comes back in warnings; verify the output before claiming
+        caption delivery.
       list_presets() -> {presets}
       load_preset(name) -> {success}
       save_preset(name) -> {success}
@@ -19577,8 +19594,12 @@ def render(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         if ignored_settings:
             result["ignored_settings"] = ignored_settings
         # Accepted-then-ignored key combinations (21.0.4 AddFrameHandles under
-        # UseFullExtents) read as a clean success without this.
-        warnings = _render_settings_warnings(settings)
+        # UseFullExtents; 19.x ExportSubtitle) read as a clean success without this.
+        try:
+            _ver_major = int((get_resolve().GetVersion() or [0])[0])
+        except Exception:
+            _ver_major = None
+        warnings = _render_settings_warnings(settings, version_major=_ver_major)
         if warnings:
             result["warnings"] = warnings
         return result

package/src/utils/api_truth.py

@@ -2737,6 +2737,60 @@ API_TRUTH: List[Dict[str, Any]] = [
         "submit": "bug",
         "mitigation": ["editorial.verify_roundtrip markersNotInExport"],
     },
+    {
+        "symbol": "MediaPool.ImportTimelineFromFile EDL (drops BL fades)",
+        "object": "MediaPool",
+        "signature": "(filePath.edl, importOptions) -> Timeline",
+        "reality": "EDL dissolves involving the BL (black) reel are dropped "
+                   "silently on import (measured on Studio 19.1.3.7, E91): a "
+                   "CMX fade-in (zero-length BL cut + D event) vanishes "
+                   "wholesale — frame 0 renders at full brightness — and a "
+                   "fade-out to a BL leg imports the BL as a Solid Color "
+                   "generator but drops the dissolve, leaving a hard cut to "
+                   "black. Import succeeds; the importer authors dissolves "
+                   "normally between two real media clips. A related law: a "
+                   "hand-authored SINGLE-SIDED transition element (span at a "
+                   "lone clip head or tail, only one neighboring item) "
+                   "refuses to import entirely — Resolve creates no timeline.",
+        "recommended": "Conform EDLs with fades through "
+                       "drt.assemble_from_interchange: BL legs author as "
+                       "Solid Color generator elements and the fades as real "
+                       "clip-to-generator dissolves (render-verified: luma "
+                       "ramps 18->123 across a 24f fade-in and 123->16 "
+                       "across the fade-out, black tail holding 16). Audio "
+                       "BL fades (to silence) drop with a stated reason — "
+                       "there is no silence source to cross-fade against.",
+        "tags": ["edl", "import", "transitions", "fades", "silent-failure"],
+        "submit": "bug",
+        "mitigation": ["drt.assemble_from_interchange black-leg authoring"],
+    },
+    {
+        "symbol": "Project.SetRenderSettings ExportSubtitle/SubtitleFormat (inert on 19.x)",
+        "object": "Project",
+        "signature": "({'ExportSubtitle': bool, 'SubtitleFormat': str}) -> bool",
+        "reality": "On Studio 19.1.3.7 the subtitle-delivery keys documented "
+                   "in the Resolve 21 API reference are accepted and fully "
+                   "inert: SetRenderSettings returns True for all three "
+                   "SubtitleFormat modes ('BurnIn', 'SeparateFile', "
+                   "'EmbeddedCaptions'), and the renders carry no burned-in "
+                   "pixels (frame-extract verified), no sidecar subtitle "
+                   "file, and no embedded caption track (stream-probe "
+                   "verified) — with the subtitle cues readback-verified on "
+                   "the timeline and the subtitle track enabled. Quirk: "
+                   "ExportSubtitle alone returns False; the pair returns "
+                   "True. All three outputs are stream-identical to a "
+                   "no-subtitle render.",
+        "recommended": "Do not trust a True return for subtitle delivery on "
+                       "a pre-21 host — verify the output (extract a frame "
+                       "for burn-in, list the target directory for a "
+                       "sidecar, ffprobe streams for embedded captions). On "
+                       "19.x subtitle export requires the UI render page. "
+                       "render.set_settings warns when these keys are set on "
+                       "a pre-21 host.",
+        "tags": ["render", "subtitle", "burn-in", "silent-failure", "version-gated"],
+        "submit": "bug",
+        "mitigation": ["render.set_settings warnings"],
+    },
 ]