davinci-resolve-mcp 2.215.0 → 2.215.2

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 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.215.2 — the granular server accepts Resolve 21.1's lowercase item types; the 21.1 typed API ships as reference
+
+Both contributed by @legionsound (#204, #205), measured on Studio 21.1.0.14.
+
+### Fixed
+
+- **Granular timeline-item tools rejected ordinary video clips on Resolve
+  21.1.** Studio 21.1 returns lowercase `video` / `audio` from
+  `TimelineItem.GetType()`, as its shipped typed API declares, and the
+  granular guards compared against `Video` / `Audio` — so every transform,
+  crop, composite, stabilization and keyframe-mode write refused a plain video
+  clip, and the property resource omitted the type-specific sections. Type
+  values are now normalised for the checks, title-case still passes, a
+  missing or non-string type is unknown rather than a clip, and the optional
+  `GetMediaType` accessor is only called when it is callable (on the probed
+  21.1 clip it is not). Public `type` values are unchanged. The compound
+  server has no title-case comparison of its own, so the class was confined
+  to the granular layer. Seven regression tests drive the real handlers; the
+  contributor's live write on a synthetic clip changed the rendered frame as
+  expected. (#204)
+- **On landing:** the accompanying live script selected a clip with
+  `item.GetMediaPoolItem()`, which on Studio 19.1.3.7 resolves to `None` on a
+  conform timeline's items and raised before the read; it now checks the
+  accessor is callable first.
+
+### Documentation
+
+- **Blackmagic's 21.1 `DaVinciResolveScript.pyi` is bundled unmodified** under
+  `docs/reference/`, with its SHA-256, the shipped 21.1 scripting changelog,
+  and a provenance note; the legacy README snapshot and every
+  `resolve_scripting_api.txt line N` anchor are untouched, as the #197 review
+  asked. `scripts/audit_typed_api.py` inventories the stub's 410 methods and
+  46 option dictionaries against executable references in `src/`, marking
+  same-name methods on different classes as receiver-unresolved rather than
+  covered; it reports candidate gaps and makes no coverage claim. (#205)
+
+### Validation
+
+- Both PRs' tests plus the full offline suite, drift guards and the advanced
+  Node suite. The lowercase behaviour is the contributor's measurement on
+  21.1.0.14 and is recorded as such; title-case compatibility is pinned by
+  the unit tests, not by a live read here.
+
+## What's New in v2.215.1 — single-frame capture survives per-clip render mode and a vanished stills folder
+
+### Fixed
+
+- **`timeline_frame capture` forces Single-clip render mode and restores it.**
+  Measured 2026-09-09 on a project whose delivery preset was "Individual
+  clips": every single-frame capture reported success, wrote no file, and took
+  30+ seconds, because in that mode Resolve ignores `CustomName`, renders the
+  whole clip under its own naming, and the frame this helper waits for never
+  appears. The helper now reads `GetCurrentRenderMode()`, switches to single
+  clip (1) for the render, puts the mode back afterwards, and refuses with
+  `RENDER_MODE_REFUSED` before adding a job if the switch fails.
+- **The shared stills folder is recreated before every directory listing.**
+  Every sandbox path redirects to one `~/Documents/resolve-stills`, and the
+  helper's own cleanup removes it once it empties, so a concurrent capture (or
+  anything else) can take it away between the makedirs at the top and the
+  `os.listdir` that follows. Frame 81 of a 214-frame QC batch died on exactly
+  that. Recreate, do not assume.
+
+### Measured (not code)
+
+- A per-clip `.drx` carries the clip node graph losslessly (applying a clip's
+  own emitted grade back onto it re-renders bit-identically, PSNR 99 on 5/5),
+  but NOT colour-group pre/post grades, NOT Colour-page input sizing, and with
+  `grade_mode` 0 NOT keyframes. A traced conform whose source used groups needs
+  the group grades carried separately.
 ## What's New in v2.215.0 — mutating operations write a structured operation log; the free-edition bridge is version-qualified for Resolve 21.1
 
 ### Added

package/README.md

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

package/docs/README.md

@@ -22,6 +22,8 @@ ignored scratch folders such as `docs/_scratch/`.
   correction guidance and Resolve color API boundaries.
 - [Resolve Scripting API Reference](reference/resolve_scripting_api.txt) — bundled
   Resolve scripting API text used for parity checks.
+- [Resolve 21.1 Typed API](reference/resolve-211-typed-api.md) — vendor stub,
+  scripting changelog, provenance and an executable-reference inventory.
 - [Contributing and Project Layout](contributing.md) — contribution workflow,
   platform support, security notes, and repository structure.
 - [Release Process](process/release-process.md) — maintainer release checklist.

package/docs/reference/resolve-211-typed-api.md

@@ -0,0 +1,78 @@
+# Resolve 21.1 typed API snapshot
+
+The vendor-shipped [DaVinciResolveScript.pyi](DaVinciResolveScript.pyi) preserves
+Blackmagic's typed Resolve API separately from the legacy
+[README snapshot](resolve_scripting_api.txt). The legacy file and its line
+anchors are unchanged. The accompanying
+[scripting changelog](resolve_scripting_changelog_21.1.md) lists the 21.1 additions.
+
+## Provenance
+
+Collected September 9, 2026 from the installed official MCP's
+`get_scripting_api(as_file=True)` on macOS, DaVinci Resolve Studio **21.1.0.14**.
+The changelog was copied from the installed `Developer/Scripting/CHANGELOG.md`
+and is dated September 1, 2026. The stub is unmodified vendor reference material;
+it is not authored by this project. Its SHA-256 is
+`00078fa1256851b9807621a4eea5e670f4266b0e7003763cba4a62655543f0ec`.
+
+This supplies the typed snapshot requested in
+[the review of #197](https://github.com/samuelgursky/davinci-resolve-mcp/pull/197#issuecomment-5584959121).
+Future refreshes should replace the whole vendor file, retain provenance and
+review the signature/option changes, rather than patch selected methods into it.
+
+## Diagnostic inventory
+
+Run from the repository root:
+
+```sh
+python scripts/audit_typed_api.py
+python scripts/audit_typed_api.py --json > /tmp/resolve-api-inventory.json
+```
+
+The JSON includes every public class method, its signatures and source line,
+all TypedDict option fields and their descriptions, and source references split
+between compound, granular and helper files. An alternate installed stub can be
+passed with `--stub`; `--source-root` selects an alternate source tree.
+
+The 21.1 snapshot has **410 unique class-qualified public methods** and **46
+TypedDicts containing 513 fields**. Compared with the 361 methods parsed from
+the legacy README, 57 are newly represented and eight legacy names are absent
+from the stub. That does **not** mean 57 newly introduced runtime functions or
+eight removed functions: newly documented existing methods and deprecated
+aliases are part of the difference. For example, the 21.1 README deprecates
+`GetSetting`/`SetSetting` in favor of `GetSettings`/`SetSettings` and
+`GetProperty`/`SetProperty` in favor of their plural forms. The special
+four-argument Super Scale `SetSetting` form is explicitly not deprecated.
+
+At main `91d03a52c139002061e325824004162366f0902c`, 50 method names had no
+executable attribute or literal-getattr reference under `src/`. These are
+**candidate gaps**, not a claim that 50 user-facing features are missing.
+
+## What this audit proves, and what it does not
+
+- Comments and docstrings cannot count as executable coverage. In particular,
+  `CreateMulticamClip` mentioned in the API-truth ledger is not a wrapper.
+- Class identity is preserved in the inventory, but Python receiver types are
+  **not inferred**. A `pm.GetCurrentProject()` reference does not prove that
+  the new `Resolve.GetCurrentProject()` utility is used. Matching names carry
+  `unresolved_receiver`, not `covered`.
+- A literal `getattr` can be a capability probe rather than an invocation.
+  Attribute references and direct calls have separate kinds in the report.
+- A helper reference does not prove that both public server layers expose it,
+  or that all arguments/options are forwarded. Follow each candidate through
+  action dispatch, parameter validation, version guards and response shaping.
+- Computed dispatch and equivalent older APIs require manual review.
+- The script only parses files. It does not import source modules, connect to
+  Resolve, mutate projects, or establish behavior.
+
+Exit zero means the inventory completed, **not** that API parity passed. Empty
+or malformed inputs fail rather than reporting a false clean inventory. The
+existing `audit_api_parity.py` guard remains unchanged; promoting this diagnostic
+to a coverage gate requires an explicitly reviewed method-to-action manifest.
+
+## Validation
+
+`python -m unittest tests.test_typed_api_audit` covers comment-only false
+coverage, class-name collisions, source layers, call versus getattr references,
+option-field descriptions, overload preservation and invalid input. No Resolve
+behavior is changed, so no live mutation test is required for this contribution.

package/docs/reference/resolve_scripting_changelog_21.1.md

@@ -0,0 +1,132 @@
+# DaVinci Resolve Scripting API Changelog
+
+*Last Updated: 1 Sep 2026*
+
+This file documents scripting changes by version. For the overall DaVinci Resolve Scripting API, please refer to
+Developer/Scripting/README.md and DaVinciResolveScript.pyi.
+
+## 21.1
+
+Notes:
+
+- Python 2 is no longer supported.
+- Built-in Python support for script menu and console scripts.
+- Overloaded function signatures are deprecated.
+
+Added:
+
+- Resolve Keyboard Presets - Load/Delete/Import/Export/GetCurrent/Get List for KeyboardPreset.
+- Project Settings Presets - Set/Delete/Import/Export/Update/Save/Get List for ProjectSettingsPreset.
+- Render Presets - Project.UpdateRenderPreset, SetQuickExportEnabledForRenderPreset.
+- Audio Render APIs - Project.GetAudioRenderCodecs, GetAudioRenderFormats.
+- Media Transcription - MediaPoolItem.GetTranscription.
+- Multicam APIs - MediaPool.CreateMulticamClip, TimelineItem.FlattenMulticam, PerformMulticamSmartSwitch, Timeline.AutoAlignClips.
+- TimelineItem properties - Get/Set Property includes native audio properties and enabled states.
+- TimelineItem properties - Get/Set Fades, Speed, OutputBlanking, UseTimelineForOutputBlanking and GetType.
+- Transition API - TimelineItem.AddTransition.
+- Timeline Output blanking - Timeline.Get/SetOutputBlanking.
+- Timeline Audio Normalization - Timeline.GetNormalizeAudioModes, NormalizeAudioLevel.
+- Set Audio Mappings - MediaPoolItem.SetAudioMapping, TimelineItem.SetSourceAudioChannelMapping.
+- Media Storage Clone - MediaStorage.StartCloneMedia, StopCloneMedia, GetCloneStatus, SetCloneToolSettings.
+- DCTL development - resolve.ValidateDCTL, EncryptDCTL.
+- Utility functions - resolve.Get CurrentProject/CurrentTimeline/MediaPool/Gallery.
+
+## 21.0.4
+
+Added:
+
+- Timeline.GetSelectedClips
+- Project.SetRenderSettings - options for handles, full extents and data burn.
+
+## 21.0.3
+
+Addressed:
+
+- Incorrect audio mapping results in some scenarios.
+
+## 21.0.1
+
+Addressed:
+
+- GenerateSpeech API character limit issue.
+
+## 21.0
+
+Added:
+
+- Optional useSpeakerDetection argument for Folder.TranscribeAudio and MediaPoolItem.TranscribeAudio.
+- PerformAudioClassification and ClearAudioClassification for Folder and MediaPoolItem.
+- RemoveMotionBlur({deblurOption}) for Folder and MediaPoolItem.
+- AnalyzeForIntellisearch(identifyFaces, isBetterMode) for Folder and MediaPoolItem.
+- New Marker color enumerated type - currently used only in AnalyzeForSlate APIs.
+- AnalyzeForSlate(markerColor) for Folder and MediaPoolItem.
+- Resolve.DisableBackgroundTasksForCurrentResolveSession
+- Project.GenerateSpeech({speechGenerationSettings}, timecode)
+
+## 20.3.2
+
+Addressed:
+
+- AppendToTimeline failure when no media pool clip is selected.
+
+## 20.2.2
+
+Added:
+
+- ProjectManager.CreateProject supports optional mediaLocationPath parameter.
+- Resolve.GetFairlightPresets
+- Project.ApplyFairlightPresetToCurrentTimeline(preset_name)
+
+Addressed:
+
+- GetRenderCodecs(renderFormat) missing some valid codecs.
+- SetVoiceIsolationState incorrect behavior in some scenarios.
+- AppendToTimeline validating trackIndex as video track indices in 'Audio Only' mode.
+
+## 20.2.1
+
+Addressed:
+
+- TimelineItem.GetName not returning subtitle text content.
+- Project.SetSetting('colorAcesODT', value) not working for some values.
+
+## 20.2
+
+Added:
+
+- TimelineItem and MediaPoolItem support for SetName.
+- Render Settings: ExportSubtitle (Bool) and SubtitleFormat (string) options.
+- TimelineItem.ResetAllNodeColors
+
+## 20.1
+
+Added:
+
+- Timeline.GetVoiceIsolationState(trackIndex)
+- Timeline.SetVoiceIsolationState(trackIndex, {VoiceIsolationState})
+- TimelineItem.GetVoiceIsolationState
+- TimelineItem.EnableVoiceIsolationState({VoiceIsolationState})
+
+Addressed:
+
+- Interlaced clip frame offset issues in multiple APIs.
+
+## 20.0.1
+
+Addressed:
+
+- MediaPool.AppendToTimeline not working in some scenarios.
+
+## 20.0
+
+Added:
+
+- MediaPoolItem.LinkFullResolutionMedia(fullResMediaPath)
+- MediaPoolItem.ReplaceClipPreserveSubClip(filePath)
+- MediaPoolItem.MonitorGrowingFile
+
+Addressed:
+
+- TimelineItem.GetRightExtents return (it now returns offset between right edit point and media extents end).
+- Occasional lags for some scripting APIs.
+- AddFusionComp sometimes showing incorrect composition.

package/install.py

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

package/scripts/audit_typed_api.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Inventory a shipped Resolve .pyi against executable source references.
+
+Diagnostic only: absence is a candidate gap, presence is NOT wrapper coverage.
+Receiver types are not inferred, and arbitrary dynamic dispatch is unresolved.
+This complements the legacy README audit without changing its baseline.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def inventory_stub(text: str) -> dict:
+    """Preserve class identity, signatures, docs, and typed option fields."""
+    methods, options = {}, {}
+    for cls in ast.parse(text).body:
+        if not isinstance(cls, ast.ClassDef):
+            continue
+        for node in cls.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and not node.name.startswith('_'):
+                key = f'{cls.name}.{node.name}'
+                signature = f'{node.name}({ast.unparse(node.args)})'
+                if node.returns is not None:
+                    signature += f' -> {ast.unparse(node.returns)}'
+                row = methods.setdefault(key, {'signatures': [], 'line': node.lineno,
+                                                'description': ast.get_docstring(node)})
+                row['signatures'].append(signature)
+        if any(ast.unparse(base).endswith('TypedDict') for base in cls.bases):
+            fields = {}
+            for index, node in enumerate(cls.body):
+                if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+                    doc = None
+                    if index + 1 < len(cls.body):
+                        following = cls.body[index + 1]
+                        if (isinstance(following, ast.Expr) and isinstance(following.value, ast.Constant)
+                                and isinstance(following.value.value, str)):
+                            doc = following.value.value
+                    fields[node.target.id] = {'type': ast.unparse(node.annotation),
+                                              'line': node.lineno, 'description': doc}
+            options[cls.name] = fields
+    if not methods:
+        raise ValueError('No public class methods found; refusing an empty API inventory')
+    return {'methods': methods, 'option_types': options}
+
+
+def source_references(text: str) -> list[dict]:
+    """Record executable syntax, never docstrings/comments as fake coverage."""
+    tree = ast.parse(text)
+    parents = {child: parent for parent in ast.walk(tree) for child in ast.iter_child_nodes(parent)}
+    refs = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Attribute):
+            parent = parents.get(node)
+            refs.append({'method_name': node.attr, 'line': node.lineno,
+                         'receiver': ast.unparse(node.value),
+                         'kind': 'call' if isinstance(parent, ast.Call) and parent.func is node else 'attribute'})
+        elif (isinstance(node, ast.Call) and isinstance(node.func, ast.Name)
+              and node.func.id == 'getattr' and len(node.args) > 1
+              and isinstance(node.args[1], ast.Constant) and isinstance(node.args[1].value, str)):
+            refs.append({'method_name': node.args[1].value, 'line': node.lineno,
+                         'receiver': ast.unparse(node.args[0]), 'kind': 'getattr'})
+    return refs
+
+
+def build_report(stub_text: str, sources: dict[str, str]) -> dict:
+    inventory = inventory_stub(stub_text)
+    by_name = {}
+    for path, text in sorted(sources.items()):
+        layer = ('compound' if path == 'src/server.py' else
+                 'granular' if path.startswith('src/granular/') else 'helper')
+        for ref in source_references(text):
+            by_name.setdefault(ref['method_name'], []).append({'path': path, 'layer': layer, **ref})
+    for key, method in inventory['methods'].items():
+        refs = by_name.get(key.rsplit('.', 1)[1], [])
+        method['name_references'] = refs
+        method['status'] = 'unresolved_receiver' if refs else 'no_executable_name_reference'
+    candidates = [key for key, row in inventory['methods'].items() if not row['name_references']]
+    return {'schema_version': 1, 'method_count': len(inventory['methods']),
+            'candidate_count': len(candidates), 'candidate_gaps': candidates,
+            'limitations': ['References are matched by method name, not receiver type.',
+                            'A call/reference does not prove public action or parameter coverage.',
+                            'Literal getattr may only probe availability.',
+                            'Computed dispatch and equivalent older methods need manual review.',
+                            'This inventory does not invoke Resolve or validate behavior.'],
+            **inventory}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--stub', type=Path, default=ROOT / 'docs/reference/DaVinciResolveScript.pyi')
+    parser.add_argument('--source-root', type=Path, default=ROOT / 'src')
+    parser.add_argument('--json', action='store_true', help='Print the full method/option/reference inventory')
+    args = parser.parse_args()
+    paths = sorted(args.source_root.rglob('*.py'))
+    if not paths:
+        parser.error('No Python source files found; refusing an empty source inventory')
+    sources = {'src/' + path.relative_to(args.source_root).as_posix(): path.read_text(encoding='utf-8')
+               for path in paths}
+    report = build_report(args.stub.read_text(encoding='utf-8'), sources)
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(f"{report['method_count']} class-qualified methods; {report['candidate_count']} candidate gaps")
+        for name in report['candidate_gaps']:
+            print(name)
+        print('Diagnostic only: name references are not proof of wrapper coverage or live behavior.')
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/src/granular/common.py

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

@@ -5,6 +5,25 @@ from src.utils.clip_colors import clip_color_refusal
 
 resolve = ResolveProxy()
 
+
+def _item_type(item, method="GetType"):
+    """Normalize type values without assuming an optional API is callable.
+
+    Resolve 21.1 documents lowercase types. Keep title-case compatibility,
+    and treat missing/non-string results as unknown rather than as a clip.
+    """
+    getter = getattr(item, method, None)
+    if not callable(getter):
+        return ""
+    value = getter()
+    return value.lower() if isinstance(value, str) else ""
+
+
+def _has_audio_type(item):
+    return (_item_type(item) == "audio"
+            or _item_type(item, "GetMediaType") == "audio")
+
+
 @mcp.resource("resolve://timeline-item/{timeline_item_id}")
 def get_timeline_item_properties(timeline_item_id: str) -> Dict[str, Any]:
     """Get properties of a specific timeline item by ID.
@@ -65,7 +84,7 @@ def get_timeline_item_properties(timeline_item_id: str) -> Dict[str, Any]:
         }
         
         # Get additional properties if it's a video item
-        if timeline_item.GetType() == "Video":
+        if _item_type(timeline_item) == "video":
             # Transform properties
             properties["transform"] = {
                 "position": {
@@ -118,7 +137,7 @@ def get_timeline_item_properties(timeline_item_id: str) -> Dict[str, Any]:
             }
         
         # Audio-specific properties
-        if timeline_item.GetType() == "Audio" or timeline_item.GetMediaType() == "Audio":
+        if _has_audio_type(timeline_item):
             properties["audio"] = {
                 "volume": timeline_item.GetProperty("Volume"),
                 "pan": timeline_item.GetProperty("Pan"),
@@ -239,7 +258,7 @@ def set_timeline_item_transform(timeline_item_id: str,
         if not timeline_item:
             return f"Error: Video timeline item with ID '{timeline_item_id}' not found"
         
-        if timeline_item.GetType() != "Video":
+        if _item_type(timeline_item) != "video":
             return f"Error: Timeline item with ID '{timeline_item_id}' is not a video item"
         
         # Set the property
@@ -299,7 +318,7 @@ def set_timeline_item_crop(timeline_item_id: str,
         if not timeline_item:
             return f"Error: Video timeline item with ID '{timeline_item_id}' not found"
         
-        if timeline_item.GetType() != "Video":
+        if _item_type(timeline_item) != "video":
             return f"Error: Timeline item with ID '{timeline_item_id}' is not a video item"
         
         # Set the property
@@ -368,7 +387,7 @@ def set_timeline_item_composite(timeline_item_id: str,
         if not timeline_item:
             return f"Error: Video timeline item with ID '{timeline_item_id}' not found"
         
-        if timeline_item.GetType() != "Video":
+        if _item_type(timeline_item) != "video":
             return f"Error: Timeline item with ID '{timeline_item_id}' is not a video item"
         
         success = True
@@ -529,7 +548,7 @@ def set_timeline_item_stabilization(timeline_item_id: str,
         if not timeline_item:
             return f"Error: Video timeline item with ID '{timeline_item_id}' not found"
         
-        if timeline_item.GetType() != "Video":
+        if _item_type(timeline_item) != "video":
             return f"Error: Timeline item with ID '{timeline_item_id}' is not a video item"
         
         success = True
@@ -635,7 +654,7 @@ def set_timeline_item_audio(timeline_item_id: str,
             return f"Error: Timeline item with ID '{timeline_item_id}' not found"
         
         # Check if the item has audio capabilities
-        if not is_audio and timeline_item.GetMediaType() != "Audio":
+        if not is_audio and not _has_audio_type(timeline_item):
             return f"Error: Timeline item with ID '{timeline_item_id}' does not have audio properties"
         
         success = True
@@ -737,7 +756,7 @@ def get_timeline_item_keyframes(timeline_item_id: str, property_name: str) -> Di
         audio_properties = ['Volume', 'Pan']
         
         # Check if it's a video item
-        if timeline_item.GetType() == "Video":
+        if _item_type(timeline_item) == "video":
             # Check each property to see if it has keyframes
             for prop in video_properties:
                 if timeline_item.GetKeyframeCount(prop) > 0:
@@ -758,7 +777,7 @@ def get_timeline_item_keyframes(timeline_item_id: str, property_name: str) -> Di
                         })
         
         # Check if it has audio properties (could be video with audio or audio-only)
-        if timeline_item.GetType() == "Audio" or timeline_item.GetMediaType() == "Audio":
+        if _has_audio_type(timeline_item):
             # Check each audio property for keyframes
             for prop in audio_properties:
                 if timeline_item.GetKeyframeCount(prop) > 0:
@@ -877,7 +896,7 @@ def add_keyframe(timeline_item_id: str, property_name: str, frame: int, value: f
         if is_audio and property_name not in audio_properties:
             return f"Error: Property '{property_name}' is not available for audio items"
         
-        if not is_audio and property_name not in video_properties and timeline_item.GetType() != "Video":
+        if not is_audio and property_name not in video_properties and _item_type(timeline_item) != "video":
             return f"Error: Property '{property_name}' is not available for this item type"
             
         # Validate frame is within the item's range
@@ -1241,7 +1260,7 @@ def enable_keyframes(timeline_item_id: str, keyframe_mode: str = "All") -> str:
         if not timeline_item:
             return f"Error: Video timeline item with ID '{timeline_item_id}' not found"
         
-        if timeline_item.GetType() != "Video":
+        if _item_type(timeline_item) != "video":
             return f"Error: Timeline item with ID '{timeline_item_id}' is not a video item"
         
         # Set the keyframe mode

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.215.0"
+VERSION = "2.215.2"
 
 import base64
 import os
@@ -14963,6 +14963,18 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
         original_fc = proj.GetCurrentRenderFormatAndCodec()
     except Exception:
         pass
+    # Render MODE is project state too, and it decides whether the capture can
+    # work at all. In "Individual clips" mode (0) Resolve ignores CustomName,
+    # renders the WHOLE clip under the frame's own file naming, and the
+    # single-frame file this helper waits for never appears — measured
+    # 2026-09-09 on a project whose delivery preset was per-clip: every capture
+    # reported success, wrote no file, and took 30+ s rendering the clip.
+    # Force single clip (1) for the capture and put the mode back afterwards.
+    original_mode = None
+    try:
+        original_mode = proj.GetCurrentRenderMode()
+    except Exception:
+        original_mode = None
     # Rendering pulls Resolve onto the Deliver page and moves the playhead;
     # measured leaving the user on Deliver at a different frame. Both are ours
     # to put back.
@@ -15014,6 +15026,16 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
 
     job = None
     try:
+        if original_mode is not None and original_mode != 1:
+            if not proj.SetCurrentRenderMode(1):
+                return _err(
+                    "Resolve refused to switch the render mode to single clip; in "
+                    "individual-clips mode a single-frame capture renders the whole clip "
+                    "under Resolve's own naming and the captured file never appears",
+                    code="RENDER_MODE_REFUSED", category="api_error",
+                    remediation="render(action='set_mode', params={'mode': 1}) then retry.",
+                    state={"render_mode": original_mode},
+                )
         codecs = proj.GetRenderCodecs("JPEG" if fmt == "jpg" else fmt.upper()) or {}
         codec = list(codecs.values())[0] if codecs else fmt
         if not proj.SetCurrentRenderFormatAndCodec(fmt, codec):
@@ -15040,6 +15062,13 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
         job = proj.AddRenderJob()
         if not job:
             return _err("AddRenderJob returned nothing", code="RENDER_JOB_FAILED", category="api_error")
+        # The folder is shared (every sandbox path redirects to one
+        # ~/Documents/resolve-stills) and the cleanup below removes it when it
+        # empties, so another capture — or anything else — can take it away
+        # between the makedirs above and here. Measured 2026-09-09: frame 81 of a
+        # 214-frame QC batch died in os.listdir on the missing folder. Recreate,
+        # don't assume.
+        os.makedirs(folder, exist_ok=True)
         before = set(os.listdir(folder))
         # Positional on purpose: the free-edition bridge proxies method calls
         # positionally, and a keyword argument dies inside _BoundMethod with
@@ -15087,6 +15116,19 @@ def _playhead_frame_render(proj, tl, p: Dict[str, Any]):
                 proj.DeleteRenderJob(job)
             except Exception:
                 pass
+        if original_mode is not None and original_mode != 1:
+            # Same teardown contract as the format/codec restore below.
+            try:
+                restored_mode = bool(proj.SetCurrentRenderMode(original_mode))
+            except Exception as exc:
+                restored_mode, mode_exc = False, exc
+            else:
+                mode_exc = None
+            if not restored_mode:
+                logger.warning(
+                    "frame capture could not restore render mode %r: %s",
+                    original_mode, mode_exc or "SetCurrentRenderMode returned False",
+                )
         if original_fc:
             # A failed restore leaves the Deliver page on the capture's format
             # and codec, which the user's next render would silently inherit.