davinci-resolve-mcp 2.218.2 → 2.219.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 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.219.0 — native Resolve 21.1 multicam creation and flattening
+
+Contributed by @legionsound (#211), live-validated on Studio 21.1.0.14.
+
+### Added
+
+- **`media_pool create_multicam_clip`**, with the granular twin
+  `create_multicam_clip`, calling 21.1's native `CreateMulticamClip`. It takes
+  a list of media-pool unique IDs and an options dictionary covering all
+  eleven documented `MulticamOptions` fields. Enum fields accept either a
+  documented Resolve constant name or an integral native value; omitted fields
+  stay omitted rather than being filled with invented defaults. It returns the
+  ids and names of the clips **actually created**, and an empty native result
+  stays `success: false`.
+- **`timeline_item flatten_multicam`**, with the granular twin
+  `flatten_timeline_item_multicam`, calling native `FlattenMulticam` with
+  either documented grade constant. Flattening replaces the item, so the tool
+  documentation tells callers to re-query the track afterwards.
+- Every clip ID is resolved **before** anything is written, and an unknown or
+  duplicated ID refuses with nothing created. That is all-or-nothing input
+  resolution, not a transaction — the module says so in its own docstring
+  rather than implying a guarantee the native call does not offer.
+
+### Changed
+
+- Both actions are registered in **both** write tables — the
+  `destructive_hook` registry and the MEDIUM-risk set in
+  `execution_lifecycle` — so safe mode, the dry-run refusal, the audit log and
+  the operation log all treat them as the mutations they are. Verified by
+  probing the classifier directly rather than reading the diff. Tool count 368
+  → 370 across the docs and the generated agent-rule files.
+- The existing stacked-timeline multicam workflow is unchanged and still
+  available; the native route is an addition, not a replacement.
+
+### Validation
+
+- Full suite green: 3,453 passed, 1 skipped. Both write tables probed directly:
+  `media_pool.create_multicam_clip` and `timeline_item.flatten_multicam` each
+  classify MEDIUM / destructive / recognised.
+- The return shape is right by documentation as well as by measurement — the
+  shipped 21.1 stub declares `CreateMulticamClip(clips, multicamOptions) ->
+  list[MediaPoolItem]`.
+- Live evidence is @legionsound's, measured on Studio 21.1.0.14 with synthetic
+  media in a disposable project, and this was the family where a **rendered**
+  comparison rather than a readback was the bar it had to clear: both
+  interfaces created native multicam items, rendered, flattened with
+  `COPY_GRADE`, and rendered again — all four complete decoded RGB movies
+  identical at 144 frames, media type becoming Video, clip span unchanged.
+  Not reproduced here; this machine is Studio 19.1.3.7, below the 21.1 floor,
+  where both methods refuse with their version error.
+- **What that evidence does not cover**, stated so it is not read as more: it
+  proves the natively-selected angle survives flattening in an ungraded
+  fixture. Angle ordering, alternate-angle selection, grade transfer, audio
+  routing and synchronisation are unverified. Smart Switch and
+  `AutoAlignClips` are deliberately not part of this change.
+
 ## What's New in v2.218.2 — the AddTransition null-duration boundary, measured
 
 Measured by @legionsound on Studio 21.1.0.14 (#209), recorded here; no behavior

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.218.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.219.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(368%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(370%20full)-blue.svg)](#server-modes)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
@@ -133,7 +133,7 @@ The command starts a loopback-only server and opens the control panel in your br
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
 | Compound | `src/server.py` | 36 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
-| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 368 | Power users who want one MCP tool per Resolve API method. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 370 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
 
@@ -365,7 +365,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **36** compound / **368** granular (live server) |
+| MCP Tools | **36** compound / **370** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |

package/README.zh-CN.md

@@ -2,17 +2,17 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.218.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.219.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(368%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(370%20full)-blue.svg)](#服务器模式)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#服务器模式)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![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.218.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.219.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -88,7 +88,7 @@ venv/bin/python -m src.control_panel
 | 模式 | 入口 | 工具数 | 适合谁 |
 |------|------|--------|--------|
 | Compound（复合） | `src/server.py` | 36 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
-| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 368 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 370 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -226,7 +226,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **36** 复合 / **368** 细粒度（实时服务器） |
+| MCP 工具 | **36** 复合 / **370** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -345,7 +345,7 @@ to the user as verified.
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
 | Compound (default) | `src/server.py` | 36 tools | Most workflows — keeps context lean |
-| Granular (full) | `src/server.py --full` | 368 tools | Power users needing one tool per API method |
+| Granular (full) | `src/server.py --full` | 370 tools | Power users needing one tool per API method |
 
 Resolve 21.1 adds [twelve read-only discovery controls](reference/resolve211-read-controls.md)
 for edition, presets, audio formats/codecs, normalization modes, speed, fades
@@ -2483,3 +2483,5 @@ The full API reference is in `docs/reference/resolve_scripting_api.txt`.
 Native Resolve 21.1 speed and fade setters: see [speed/fades](reference/resolve211-speed-fades.md) for options, version guards and contributor validation limits.
 
 Native 21.1 transition creation: see [transition controls](reference/resolve211-native-transitions.md) for options, item-index changes and contributor-rendered evidence.
+
+Native multicam creation and flattening: [21.1 controls](reference/resolve211-multicam.md), with contributor render evidence and remaining family coverage.

package/docs/contributing.md

@@ -64,7 +64,7 @@ davinci-resolve-mcp/
 ├── install.py                    # Universal installer (macOS/Windows/Linux)
 ├── src/
 │   ├── server.py                # Compound MCP server — 36 tools (default)
-│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 368 tools
+│   ├── resolve_mcp_server.py    # Thin full-server entrypoint — 370 tools
 │   ├── granular/                # Modular full-server implementation
 │   └── utils/                   # Platform detection, Resolve connection helpers
 ├── tests/                       # offline suite (test_*.py) + live harnesses (live_*.py):

package/docs/install.md

@@ -144,7 +144,7 @@ The MCP server comes in two modes:
 | Mode | File | Tools | Best For |
 |------|------|-------|----------|
 | **Compound** (default) | `src/server.py` | 36 | Most users — fast, clean, low context usage |
-| **Full** | `src/resolve_mcp_server.py` | 368 | Power users who want one tool per API method |
+| **Full** | `src/resolve_mcp_server.py` | 370 | Power users who want one tool per API method |
 
 The compound server's `timeline_item` tool includes dedicated actions for common workflows:
 
@@ -159,7 +159,7 @@ The compound server's `timeline_item` tool includes dedicated actions for common
 
 The installer uses the compound server by default. To use the full server:
 ```bash
-python src/server.py --full    # Launch full 368-tool server
+python src/server.py --full    # Launch full 370-tool server
 # Or point your MCP config directly at src/resolve_mcp_server.py
 ```
 

package/docs/reference/api-coverage.md

@@ -25,7 +25,7 @@ Every non-deprecated method in the bundled legacy README is represented. This
 does not claim complete coverage of the newer Resolve 21.1 typed API. The
 default compound server exposes **36 tools** that group related operations by
 action parameter, keeping LLM context windows lean. The full granular server
-provides **368 individual tools** for power users. The legacy coverage spans
+provides **370 individual tools** for power users. The legacy coverage spans
 13 API object classes. MCP-level kernel actions are tracked separately in
 [Kernel Action Coverage](../kernels/README.md).
 
@@ -633,3 +633,5 @@ Every method in the DaVinci Resolve Scripting API and its test status. Methods a
 Native speed and fade setters in both interfaces are documented in [Resolve 21.1 speed/fades](resolve211-speed-fades.md), including sampled video validation and unverified cases.
 
 Native 21.1 transition creation: see [transition controls](resolve211-native-transitions.md) for options, item-index changes and contributor-rendered evidence.
+
+Native multicam creation and flattening: [21.1 controls](resolve211-multicam.md), with contributor render evidence and remaining family coverage.

package/docs/reference/readwrite-symmetry.md

@@ -2,7 +2,7 @@
 
 # Read/Write Symmetry Audit
 
-- write-style action occurrences scanned: **120**
+- write-style action occurrences scanned: **121**
 - write-style action occurrences with a matching read: **73**
 - distinct high-signal `set_` actions without a direct/known readback: **4**
 
@@ -13,6 +13,6 @@
 - `set_keyframe_interpolation`
 - `set_node_enabled`
 
-## Low-signal (create/add/insert/apply/import — usually expected): 42 distinct names
+## Low-signal (create/add/insert/apply/import — usually expected): 43 distinct names
 
-`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_transition`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `apply_trace_plan`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`
+`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_subfolder`, `add_sync_event_markers`, `add_timeline_mattes`, `add_track`, `add_transition`, `add_version`, `apply_arri_cdl_lut`, `apply_cuts`, `apply_fairlight_preset`, `apply_grade_from_drx`, `apply_look_to_items`, `apply_spec`, `apply_trace_plan`, `create_compound_clip`, `create_fusion_clip`, `create_magic_mask`, `create_multicam_clip`, `create_stereo_clip`, `create_subtitles`, `create_timeline`, `create_timeline_from_clips`, `create_variant_from_ranges`, `import_comp`, `import_folder`, `import_from_drp`, `import_into_timeline`, `import_media`, `import_preset`, `import_project`, `import_render`, `import_timeline`, `import_timeline_checked`, `import_to_pool`, `insert_audio`, `insert_fusion_composition`, `insert_fusion_generator`, `insert_fusion_title`, `insert_generator`, `insert_ofx_generator`, `insert_title`

package/docs/reference/resolve211-multicam.md

@@ -0,0 +1,59 @@
+# Native Resolve 21.1 multicam creation and flattening
+
+Compound `media_pool create_multicam_clip` accepts `clip_ids` (media-pool unique
+IDs) and optional `options`. Granular `create_multicam_clip` takes the same
+arguments. Every ID must resolve before the native call; missing/duplicate IDs
+are errors, never silently dropped angles. Success returns the IDs and names of
+all returned multicam clips. An empty native result is success:false. This does
+not replace the existing stacked-timeline preparation workflow on older Resolve.
+
+All eleven MulticamOptions fields are supported: name, startTimecode, frameRate,
+angleSyncMode, channelConfig, multicamAudioMode, angleNameMode, splitAtGaps,
+useFullClipExtents, createBinForSourceClips and detectSameCameraClipsMode.
+Documented Resolve constant names (for example MULTICAM_ANGLE_SYNC_TIMECODE) are
+resolved against the live Resolve object. Integral native numeric constant values
+are also accepted; the wrapper does not invent their numbering. Unknown option
+keys, invalid named constants, malformed booleans and non-positive/non-finite
+frame rates are refused. Omitted options stay omitted. Resolve controls native
+defaults, including createBinForSourceClips=true, which can reorganize source
+clips in the media pool. No source files are modified by this wrapper.
+
+Compound `timeline_item flatten_multicam` and granular
+`flatten_timeline_item_multicam` use the normal 1-based track/0-based item
+locators and optional `grade_option`, default FLATTEN_MULTICAM_COPY_GRADE.
+FLATTEN_MULTICAM_RETAIN_GRADE_FROM_ANGLE is also accepted. This replaces the
+multicam item with its active angle, so re-query the timeline afterward. Native
+false stays success:false. Both methods require 21.1 and callable APIs; both
+compound actions are registered as destructive MEDIUM-risk writes in the two
+risk tables. Granular annotations also declare destructive writes. Explicit
+compound dry-run requests are refused before mutation.
+
+## Contributor validation
+
+Contributor-validated on macOS Studio 21.1.0.14 using generated red/blue media in
+a disposable 640x360/24 fps project. Both interfaces created a native Multicam
+media-pool item, appended it to a timeline, rendered it, flattened with COPY_GRADE,
+and rendered again. All four complete decoded RGB movies were identical, each
+144 frames. Flattened media type changed from Multicam to Video; start0 and
+144-frame duration were preserved. This proves preservation of the native-selected angle video in
+an ungraded fixture. It does not prove second-angle switching, grade-copy versus
+retained-grade differences, audio routing, audio synchronization, gap splitting
+or camera-detection behavior. These options are documented pass-through, not
+claimed live verified.
+
+`tests/live_resolve211_multicam.py OUTPUT_DIR` requires the named disposable
+project Codex Multicam Validation 20260909 with synthetic red.mov and blue.mov
+six-second clips. It creates timelines and render jobs and saves that project.
+Use the synthetic FFmpeg fixture commands in resolve211-native-transitions.md;
+never run the fixture against production media. Compare complete decoded frames
+from compound-before/compound-flattened/granular-before/granular-flattened.mov.
+
+Smart Switch and AutoAlignClips remain separate work. Native timecode alignment
+has positive position-readback evidence, but rendered/waveform acceptance remains
+open. Silent color-card Smart Switch returned false and is not a meaningful
+positive speaking-camera test. This contribution does not claim the entire
+multicam family completed.
+
+Do not infer angle order from clip_ids order. The wrapper forwards the requested
+source order, but this measurement establishes the selected angle and its
+preservation, not a contract for Resolve's default angle selection.

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.218.2"
+VERSION = "2.219.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
@@ -1543,7 +1543,7 @@ def verify_resolve_connection(python_path, api_path, lib_path):
 
 def print_banner():
     title = f"DaVinci Resolve MCP Server — Installer v{VERSION}"
-    subtitle = "36 compound · 368 full · 3 platforms"
+    subtitle = "36 compound · 370 full · 3 platforms"
     print()
     print(bold("  ╔══════════════════════════════════════════════════════╗"))
     print(bold(f"  ║{title:^54}║"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.218.2",
+  "version": "2.219.0",
   "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.218.2"
+VERSION = "2.219.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/granular/resolve_211.py

@@ -1,8 +1,9 @@
 """Native Resolve 21.1 discovery and editing controls."""
+from src.utils.resolve211_multicam import create_multicam, resolve_constant, GRADES
 from src.utils.resolve211_edits import validate_edit_options, validate_transition_options, transition_result
 from src.granular.common import (
     mcp, READ_ONLY_TOOL, WRITE_TOOL, DESTRUCTIVE_TOOL, get_resolve, get_current_project,
-    _get_timeline, _get_timeline_item, _requires_method, has_method,
+    _get_timeline, _get_timeline_item, _find_clip_by_id, _requires_method, has_method,
 )
 
 
@@ -198,3 +199,33 @@ def add_timeline_item_transition(options: dict, track_type: str = "video", track
     if missing:
         return missing
     return transition_result(item.AddTransition(dict(options)))
+
+
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
+def create_multicam_clip(clip_ids: list[str], options: dict | None = None) -> dict:
+    """Create native 21.1 multicam clips. Options follow MulticamOptions; named Resolve constants or numeric values accepted. Resolves every ID before writing."""
+    _, p = get_current_project()
+    if p is None:
+        return {"error": "No project currently open"}
+    mp = p.GetMediaPool()
+    missing = _requires_method(mp, "CreateMulticamClip", "21.1")
+    if missing:
+        return missing
+    return create_multicam(get_resolve(), mp, clip_ids, {} if options is None else options, _find_clip_by_id)
+
+
+@mcp.tool(annotations=DESTRUCTIVE_TOOL)
+def flatten_timeline_item_multicam(grade_option: str = "FLATTEN_MULTICAM_COPY_GRADE", track_type: str = "video", track_index: int = 1, item_index: int = 0) -> dict:
+    """Flatten a native multicam item using COPY_GRADE or RETAIN_GRADE_FROM_ANGLE. Re-query items after replacement."""
+    if track_type not in ("video", "audio") or track_index < 1 or item_index < 0:
+        return {"error": "Use video/audio, a 1-based track index and a non-negative item index"}
+    item, error = _get_timeline_item(track_type, track_index, item_index)
+    if error:
+        return error
+    missing = _requires_method(item, "FlattenMulticam", "21.1")
+    if missing:
+        return missing
+    grade, error = resolve_constant(get_resolve(), grade_option, GRADES)
+    if error:
+        return {"error": error}
+    return {"success": bool(item.FlattenMulticam(grade))}

package/src/resolve_mcp_server.py

@@ -34,7 +34,7 @@ from src.utils.update_check import start_background_update_check
 if __name__ == "__main__":
     try:
         start_background_update_check(VERSION, project_dir, logger)
-        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (368 granular tools)")
+        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (370 granular tools)")
         run_fastmcp_stdio(mcp)
     except KeyboardInterrupt:
         logger.info("Server shutdown requested")

package/src/server.py

@@ -8,10 +8,10 @@ Each tool groups related operations via an 'action' parameter.
 
 Usage:
     python src/server.py              # Start the MCP server
-    python src/server.py --full       # Start the 368-tool granular server instead
+    python src/server.py --full       # Start the 370-tool granular server instead
 """
 
-VERSION = "2.218.2"
+VERSION = "2.219.0"
 
 import base64
 import os
@@ -42,6 +42,7 @@ for p in [current_dir, project_dir]:
     if p not in sys.path:
         sys.path.insert(0, p)
 
+from src.utils.resolve211_multicam import create_multicam, resolve_constant, GRADES
 from src.utils.resolve211_edits import validate_edit_options, validate_transition_options, transition_result
 
 # Platform-specific Resolve paths
@@ -20826,6 +20827,7 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
     exist. Raw mutators below do not validate paths, support dry_run, or normalize errors.
 
     Actions:
+      create_multicam_clip(clip_ids, options?) -> {success, clips} — native 21.1 multicam creation.
       get_root_folder() -> {name, id}
       get_current_folder() -> {name, id}
       set_current_folder(path) -> {success}  — path like "Master/SubFolder"
@@ -21036,6 +21038,11 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
             created_new=True,
             versioned_name=bool(existing and create_name != p.get("name")),
         ) if tl else _err("Failed to create timeline")
+    elif action == "create_multicam_clip":
+        missing = _requires_method(mp, "CreateMulticamClip", "21.1")
+        if missing:
+            return missing
+        return create_multicam(get_resolve(), mp, p.get("clip_ids"), {} if p.get("options") is None else p["options"], _find_clip)
     elif action == "setup_multicam_timeline":
         return _setup_multicam_timeline(proj, mp, p)
     elif action == "import_timeline":
@@ -21298,7 +21305,7 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
         return _copy_clip_annotations(root, p)
     elif action == "media_pool_boundary_report":
         return _media_pool_boundary_report(mp, p)
-    return _unknown(action, ["get_root_folder","get_current_folder","set_current_folder","add_subfolder","delete_folders","move_folders","refresh","create_timeline","create_timeline_from_clips","import_timeline","delete_timelines","append_to_timeline","import_media","delete_clips","move_clips","relink","unlink","export_metadata","get_unique_id","create_stereo_clip","auto_sync_audio","get_selected","set_selected","get_clip_mattes","get_timeline_mattes","delete_clip_mattes","import_folder",*_MEDIA_POOL_KERNEL_ACTIONS])
+    return _unknown(action, ["create_multicam_clip","get_root_folder","get_current_folder","set_current_folder","add_subfolder","delete_folders","move_folders","refresh","create_timeline","create_timeline_from_clips","import_timeline","delete_timelines","append_to_timeline","import_media","delete_clips","move_clips","relink","unlink","export_metadata","get_unique_id","create_stereo_clip","auto_sync_audio","get_selected","set_selected","get_clip_mattes","get_timeline_mattes","delete_clip_mattes","import_folder",*_MEDIA_POOL_KERNEL_ACTIONS])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -26274,6 +26281,7 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
     Identify by track_type, track_index, item_index (item_index is 0-BASED: 0 = first clip; track_index is 1-based).
 
     Actions:
+      flatten_multicam(grade_option?, ...) -> {success} — native 21.1, replaces multicam with its current angle.
       add_transition(options, ...) -> {success, transition?} — native 21.1 transition; reports actual span.
       set_speed(options, ...) -> {success} — native 21.1 speed options; RippleTimeline defaults false.
       set_fades(options, ...) -> {success} — native 21.1 FadeIn/FadeOut integer frames.
@@ -26331,6 +26339,15 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
     if err:
         return err
 
+    if action == "flatten_multicam":
+        missing = _requires_method(item, "FlattenMulticam", "21.1")
+        if missing:
+            return missing
+        grade, error = resolve_constant(get_resolve(), p.get("grade_option", "FLATTEN_MULTICAM_COPY_GRADE"), GRADES)
+        if error:
+            return _err(error)
+        return {"success": bool(item.FlattenMulticam(grade))}
+
     if action == "add_transition":
         options = p.get("options")
         error = validate_transition_options(options)
@@ -26552,7 +26569,7 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
             return _err(f"Invalid interpolation. Must be one of: {', '.join(valid)}")
         return {"success": bool(item.SetKeyframeInterpolation(p["property"], p["frame"], p["interpolation"]))}
 
-    return _unknown(action, ["add_transition","set_speed","set_fades","get_speed","get_fades","get_output_blanking","get_use_timeline_for_output_blanking","get_name","get_property","set_property","get_duration","get_start","get_end","get_source_start_frame","get_source_end_frame","get_source_start_time","get_source_end_time","get_left_offset","get_right_offset","set_clip_enabled","get_clip_enabled","update_sidecar","get_unique_id","get_media_pool_item","get_stereo_convergence","get_stereo_left_window","get_stereo_right_window","get_linked_items","get_track_type_and_index","get_source_audio_mapping","load_burnin_preset","set_name","get_voice_isolation_state","set_voice_isolation_state","get_retime","set_retime","get_transform","set_transform","get_crop","set_crop","get_composite","set_composite","get_audio","set_audio","get_keyframes","add_keyframe","modify_keyframe","delete_keyframe","set_keyframe_interpolation"])
+    return _unknown(action, ["flatten_multicam","add_transition","set_speed","set_fades","get_speed","get_fades","get_output_blanking","get_use_timeline_for_output_blanking","get_name","get_property","set_property","get_duration","get_start","get_end","get_source_start_frame","get_source_end_frame","get_source_start_time","get_source_end_time","get_left_offset","get_right_offset","set_clip_enabled","get_clip_enabled","update_sidecar","get_unique_id","get_media_pool_item","get_stereo_convergence","get_stereo_left_window","get_stereo_right_window","get_linked_items","get_track_type_and_index","get_source_audio_mapping","load_burnin_preset","set_name","get_voice_isolation_state","set_voice_isolation_state","get_retime","set_retime","get_transform","set_transform","get_crop","set_crop","get_composite","set_composite","get_audio","set_audio","get_keyframes","add_keyframe","modify_keyframe","delete_keyframe","set_keyframe_interpolation"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -32674,9 +32691,9 @@ if __name__ == "__main__":
     start_background_update_check(VERSION, project_dir, logger, env=_setup_update_env())
     _install_threaded_tool_dispatch(mcp)
 
-    # Support --full flag to run the 368-tool granular server instead
+    # Support --full flag to run the 370-tool granular server instead
     if "--full" in sys.argv:
-        logger.info("Starting full 368-tool granular server...")
+        logger.info("Starting full 370-tool granular server...")
         sys.argv = [arg for arg in sys.argv if arg != "--full"]
         from src.granular import mcp as granular_mcp
 

package/src/utils/api_truth.py

@@ -878,9 +878,19 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "21.1.0.14: each of those four resolves to a "
                    "<BlackmagicFusion.PyFunctionCall object>, not None — the same "
                    "discriminator that distinguishes a real method from an absent "
-                   "one elsewhere in this registry. THE ENTRY IS NOT PROOF THE "
-                   "METHODS WORK: none of them was invoked, because doing so mutates "
-                   "the user's project. HISTORICAL, still true of 21.0.x and "
+                   "one elsewhere in this registry. That original probe did not "
+                   "invoke the methods. UPDATE: contributor-validated by "
+                   "@legionsound on Studio 21.1.0.14, macOS, 2026-09-09; not "
+                   "reproduced by the maintainer on 19.1.3.7. Both community "
+                   "interfaces created a Multicam from synthetic red/blue clips "
+                   "and flattened it with COPY_GRADE. Four complete decoded "
+                   "144-frame renders were identical before/after flattening "
+                   "and across interfaces; media type changed Multicam to Video "
+                   "without changing the selected clip span. This verifies the "
+                   "native-selected angle in an ungraded fixture, not angle "
+                   "ordering, grade transfer, audio sync or Smart Switch. See "
+                   "resolve211-multicam.md for exact limits. HISTORICAL, still "
+                   "true of 21.0.x and "
                    "earlier: there was no method to create a native multicam clip "
                    "from a set of angles; angles could be stacked onto tracks "
                    "programmatically but the multicam-clip conversion was a UI-only "

package/src/utils/destructive_hook.py

@@ -74,6 +74,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "create_timeline_from_clips",
         "append_to_timeline",
         "setup_multicam_timeline",
+        "create_multicam_clip",
         "create_stereo_clip",
         "auto_sync_audio",
         "set_clip_marks",
@@ -151,6 +152,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         # classifier did not recognise them, so safe mode, the dry-run refusal,
         # the audit log and the operation log all skipped a call that rewrites a
         # clip's speed — and, with RippleTimeline true, moves every clip after it.
+        "flatten_multicam",
         "add_transition",
         "set_speed",
         "set_fades",

package/src/utils/execution_lifecycle.py

@@ -274,6 +274,8 @@ class RiskClassificationHook(LifecycleHook):
         # Native 21.1 setters (#208): `set_speed` changes duration and, with
         # RippleTimeline true, moves every clip after it; `set_fades` rewrites
         # how the clip's edges render. Existing content altered, not deleted.
+        ("media_pool", "create_multicam_clip"),
+        ("timeline_item", "flatten_multicam"),
         ("timeline_item", "add_transition"),
         ("timeline_item", "set_speed"),
         ("timeline_item", "set_fades"),

package/src/utils/resolve211_multicam.py

@@ -0,0 +1,68 @@
+"""Native multicam options and all-or-nothing input resolution (not transactionality)."""
+import math
+
+ENUMS = {
+    'angleSyncMode': tuple('MULTICAM_ANGLE_SYNC_'+v for v in ('IN','OUT','TIMECODE','AUDIO','MARKER')),
+    'angleNameMode': tuple('MULTICAM_ANGLE_NAME_'+v for v in ('SEQUENTIAL','ANGLE','CAMERA','CLIP','FILE')),
+    'multicamAudioMode': tuple('MULTICAM_AUDIO_'+v for v in ('ADAPTIVE','SOURCE','REFERENCE','ALL')),
+    'detectSameCameraClipsMode': ('MULTICAM_DETECT_NONE',) + tuple('MULTICAM_DETECT_BY_'+v for v in ('CAMERA_NUMBER','ANGLE','REEL_NUMBER','REEL_NAME','ROLL_CARD')),
+    'channelConfig': ('AUDIO_SYNC_CHANNEL_AUTOMATIC','AUDIO_SYNC_CHANNEL_MIX'),
+}
+BOOLS = {'splitAtGaps','useFullClipExtents','createBinForSourceClips'}
+STRINGS = {'name','startTimecode'}
+GRADES = ('FLATTEN_MULTICAM_COPY_GRADE','FLATTEN_MULTICAM_RETAIN_GRADE_FROM_ANGLE')
+
+
+def resolve_constant(r, value, names):
+    if isinstance(value,str):
+        if value not in names:
+            return None, 'Unknown constant: '+value
+        native=getattr(r,value,None)
+        if type(native) not in (int,float) or not math.isfinite(native):
+            return None, 'Constant unavailable: '+value
+        return native,None
+    if type(value) in (int,float):
+        try:
+            if math.isfinite(value) and int(value)==value:
+                return value,None
+        except OverflowError:
+            pass
+    return None,'Use a documented constant name or integral native constant value'
+
+
+def create_multicam(r, mp, clip_ids, options, find_clip):
+    if not isinstance(clip_ids,list) or not clip_ids or any(not isinstance(i,str) or not i for i in clip_ids):
+        return {'error':'clip_ids must be a non-empty list of media-pool unique IDs'}
+    if len(set(clip_ids))!=len(clip_ids):
+        return {'error':'clip_ids must not contain duplicates'}
+    if not isinstance(options,dict):
+        return {'error':'options must be a dictionary'}
+    if set(options)-(set(ENUMS)|BOOLS|STRINGS|{'frameRate'}):
+        return {'error':'Unknown multicam option'}
+    normalized=dict(options)
+    for key,value in options.items():
+        if key in BOOLS:
+            if type(value) is not bool:
+                return {'error':key+' must be a boolean'}
+        elif key in STRINGS:
+            if not isinstance(value,str) or not value.strip():
+                return {'error':key+' must be a non-empty string'}
+        elif key=='frameRate':
+            try:
+                valid=type(value) in (int,float) and math.isfinite(value) and value>0
+            except OverflowError:
+                valid=False
+            if not valid:
+                return {'error':'frameRate must be a positive finite number'}
+        elif key in ENUMS:
+            normalized[key],error=resolve_constant(r,value,ENUMS[key])
+            if error:
+                return {'error':key+': '+error}
+    root=mp.GetRootFolder()
+    clips=[find_clip(root,i) for i in clip_ids]
+    if any(c is None for c in clips):
+        return {'error':'One or more clip_ids were not found; no multicam was created'}
+    created=mp.CreateMulticamClip(clips,normalized)
+    if not created:
+        return {'success':False,'clips':[]}
+    return {'success':True,'clips':[{'id':c.GetUniqueId(),'name':c.GetName()} for c in created]}

package/src/utils/resolve_versions.py

@@ -225,6 +225,8 @@ _EVIDENCE_GATES: List[Dict[str, Any]] = [
 # disagree, which is what keeps the two from drifting apart again.
 
 CODE_FLOORS: Dict[str, str] = {
+    "MediaPool.CreateMulticamClip": "21.1",
+    "TimelineItem.FlattenMulticam": "21.1",
     "TimelineItem.AddTransition": "21.1",
     "TimelineItem.SetSpeed": "21.1",
     "TimelineItem.SetFades": "21.1",