davinci-resolve-mcp 4.8.30 → 4.9.1

package/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 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 v4.9.1 — a rejected audio level write now says why, and what to do instead
+
+### Changed
+
+- **`safe_set_audio_properties` and `timeline_item set_audio` explain a
+  refused Volume / Pan / EQ write.** Resolve's scripting API has no write path
+  for audio clip or track level — `SetProperty('Volume'/'Level'/'Gain')`
+  returned `False` when measured live on 21.0.0, and `'Pan'` is the *video* transform
+  key, so it returns `True` while the audio pan does not move. A caller who saw
+  `{"write": false}` (or a `Pan` that "succeeded" and changed nothing) had no
+  way to tell "bad value" from "this cannot be written from the API at all" —
+  and the second is a different task. Both actions now attach a
+  `known_limitation` block when a level or EQ write fails, and on every `Pan`
+  write (its success is the misleading case): the
+  `api_truth` ledger entry plus the concrete ways around it (bake the gain into
+  a rendered copy of the source with ffmpeg; or save the mix once as a
+  Fairlight preset and apply it per-timeline with
+  `project_settings apply_fairlight_preset`, on Resolve 20.2.2+ only; the
+  preset methods are absent on 19.x). `AudioSyncOffset` writes are
+  unaffected — they work, and are not flagged. The legacy granular
+  `set_timeline_item_audio` returns the same guidance as its failure string.
+  Contributed by @youssefm3208-jpg (#279).
+
+### Changed on landing
+
+- A `Volume` / `Level` / `Gain` / EQ write is flagged only when Resolve
+  refused it, so a build that honours the write is not told it is impossible.
+- The Fairlight-preset workaround names its Resolve 20.2.2 floor.
+
+### Tests
+
+- `tests/test_audio_fairlight_probe.py`: a refused Volume write carries the
+  ledger entry and workarounds; a Pan write is flagged even when it returns
+  True; `AudioSyncOffset` is not flagged; an honoured Volume write is not
+  flagged; the preset workaround states its version floor.
+
+### Validation
+
+- Response-shape change only; no Resolve scripting call changed, so no live
+  run was required. The Volume/Pan behaviour is the `api_truth` ledger's live
+  measurement on 21.0.0.
+
+## What's New in v4.9.0 — bounded Media Pool import
+
+### Added
+
+- **`media_pool(action="import_bounded_media")`** creates one bounded Media
+  Pool item from a source file through
+  `MediaStorage.AddItemListToMediaPool([{media, startFrame, endFrame}])`.
+  Params: `source_path` (absolute, must exist), `start_frame`, `end_frame`,
+  `destination_folder` (must already exist) and `name`. The import lands in
+  the destination folder, which is made current only for the one call; the
+  previous current folder is restored afterwards, including when the import
+  fails. The result carries the item summary and the range properties
+  Resolve reports for it (`bounded_import_properties`). `start_frame` and
+  `end_frame` are passed through unchanged; the wrapper does not adjust for
+  end-frame inclusivity. If the rename fails after Resolve has created the
+  item, the error says the item exists under Resolve's default name and
+  returns its id in `state`, so it can be renamed or deleted rather than
+  imported twice. `media_storage.import_to_pool(item_infos)` remains the
+  raw passthrough. Contributed by @dmourati (#275).
+- Contributor-validated on Studio 21.1.1 Build 10: this itemInfo form created
+  a native subclip, and `endFrame` was inclusive (0–300 gave 301 frames).
+  That is one tested configuration, not a guarantee for other builds or
+  media types; not measured on this project's 19.1.3.7 machine.
+
+### Safety
+
+- The action is registered as a write (`destructive_hook`) and rated LOW
+  (`execution_lifecycle`): it only adds an item, and neither the source nor
+  existing pool contents change. Safe mode, the dry-run refusal and the
+  operation log now see it. `docs/reference/readwrite-symmetry.md`
+  regenerated.
+
+### Tests
+
+- `tests/test_media_pool_ingest_probe.py`: input validation never reaches
+  Resolve, the folder is restored on success and failure, `MediaStorage`
+  comes from the Resolve object rather than the project manager, and a
+  failed rename reports the created item.
+- `tests/test_execution_lifecycle.py`: the action classifies as a
+  recognised, destructive, LOW-risk write.
+
+### Validation
+
+- Offline suite green. The live result above is the contributor's, on
+  Studio 21.1.1 Build 10.
+
 ## What's New in v4.8.30 — conform_lint reports every reuse of one source
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-4.8.30-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.9.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(389%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-4.8.30-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-4.9.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(389%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)
 
-> 本翻译对应 v4.8.30 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v4.9.1 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/SKILL.md

@@ -1787,6 +1787,10 @@ helpers:
 - `probe_audio_track(track_index?)`
 - `probe_audio_item(track_type?, track_index?, item_index?)`
 - `safe_set_audio_properties(properties, restore?, dry_run?, track_type?, track_index?, item_index?)`
+  — Volume / Pan / EQ writes are not honoured by Resolve's API; a request for
+  any of them returns a `known_limitation` block with the workaround (bake gain
+  into a rendered copy, or apply a Fairlight preset). `AudioSyncOffset` writes
+  do work.
 - `audio_mix_capability_report(...)`
 - `voice_isolation_capabilities(track_index?, track_type?, item_index?)`
 - `audio_mapping_report(clip_ids?)`
@@ -1911,7 +1915,9 @@ Key actions:
 - `get_transform` / `set_transform(Pan?, Tilt?, ZoomX?, ZoomY?, RotationAngle?, ...)`
 - `get_crop` / `set_crop(CropLeft?, CropRight?, CropTop?, CropBottom?, ...)`
 - `get_composite` / `set_composite(Opacity?, CompositeMode?)`
-- `get_audio` / `set_audio(Volume?, Pan?, AudioSyncOffset?)`
+- `get_audio` / `set_audio(Volume?, Pan?, AudioSyncOffset?)` — Resolve ignores
+  Volume / Pan / EQ writes on audio (returns a `known_limitation` block); only
+  `AudioSyncOffset` / `AudioSyncOffsetIsManual` take effect
 - `get_voice_isolation_state` / `set_voice_isolation_state(state)` — Resolve
   20.1+; audio timeline items only
 - `get_keyframes(property)`, `add_keyframe(property, frame, value)`,
@@ -2194,6 +2200,19 @@ media_pool(action="safe_import_sequence", params={
   "end_index": 1048,
   "target_folder": "Master/Plates"
 })
+media_pool(action="import_bounded_media", params={
+  "source_path": "/absolute/path/source.mov",
+  "start_frame": 100,
+  "end_frame": 240,
+  "destination_folder": "Master/Selects",
+  "name": "Selected range"
+})
+# start_frame/end_frame are raw Resolve startFrame/endFrame values. The MCP does
+# not add or subtract a frame; inspect bounded_import_properties after creation.
+# Contributor-validated on DaVinci Resolve Studio 21.1.1 Build 10 (#275): this
+# itemInfo form created a native subclip, and endFrame was inclusive (0–300
+# reported 301 frames). Treat that as an observed configuration-specific result,
+# not a guarantee for every Resolve version or media type.
 media_pool(action="media_pool_boundary_report", params={"selected": True, "depth": 2})
 # Positioned append (MediaPool.AppendToTimeline([{clipInfo}, ...])) — e.g. rebuild a subtitle row after delete_clips
 media_pool(action="append_to_timeline", params={"clip_infos": [

package/docs/reference/readwrite-symmetry.md

@@ -2,7 +2,7 @@
 
 # Read/Write Symmetry Audit
 
-- write-style action occurrences scanned: **125**
+- write-style action occurrences scanned: **126**
 - write-style action occurrences with a matching read: **76**
 - 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): 44 distinct names
+## Low-signal (create/add/insert/apply/import — usually expected): 45 distinct names
 
-`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_modifier`, `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`
+`add_clip_mattes`, `add_comp`, `add_fusion_mask`, `add_modifier`, `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_bounded_media`, `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/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "4.8.30"
+VERSION = "4.9.1"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "4.8.30",
+  "version": "4.9.1",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -91,7 +91,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "4.8.30"
+VERSION = "4.9.1"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/granular/timeline_item.py

@@ -716,7 +716,17 @@ def set_timeline_item_audio(timeline_item_id: str,
             
             return f"Successfully set {' and '.join(changes)} for timeline item '{timeline_item.GetName()}'"
         else:
-            return f"Failed to set some audio properties for timeline item '{timeline_item.GetName()}'"
+            return (
+                f"Failed to set audio properties for timeline item "
+                f"'{timeline_item.GetName()}'. Resolve's scripting API has no "
+                "write path for audio level, pan, or EQ — SetProperty covers "
+                "the video transform only, so 'Volume'/'Gain' return False and "
+                "'Pan' moves the video transform, not the audio pan. Work "
+                "around it by baking the gain into a rendered copy of the "
+                "source (ffmpeg volume=NdB) and importing that, or (Resolve "
+                "20.2.2+) by saving a Fairlight preset in the UI and applying "
+                "it with project_settings apply_fairlight_preset."
+            )
     except Exception as e:
         return f"Error setting timeline item audio properties: {str(e)}"
 

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "4.8.30"
+VERSION = "4.9.1"
 
 import base64
 import os
@@ -803,10 +803,13 @@ edits audio files with no Resolve open. Plan/measure offline, apply live.
 - Offline `audio`: split (silence/TC/intervals) / trim / convert (needs ffmpeg on
   PATH — GPL, not bundled). Align/loudness-measure not yet vendored.
 
-Timeline audio SetProperty (e.g. Volume) can return false for some item types;
-the public API exposes no Fairlight automation curves — use fairlight for bus
-structure only. The offline audio ops write NEW files to scratch, never over
-source (AGENTS.md).
+Timeline audio SetProperty for level/pan/EQ does not work — 'Volume'/'Gain'
+return false and 'Pan' writes the video transform, not the audio pan; the
+public API exposes no Fairlight faders or automation curves. safe_set_audio_properties
+and timeline_item set_audio return a `known_limitation` block pointing at the
+fix: bake the gain into a rendered copy of the source, or apply a saved
+Fairlight preset. Use fairlight for bus structure only. The offline audio ops
+write NEW files to scratch, never over source (AGENTS.md).
 
 Depth: docs/kernels/audio-fairlight-kernel.md."""
 
@@ -8807,7 +8810,7 @@ def _audio_capabilities():
         "partially_supported": {
             "voice_isolation": "Track/item voice isolation depends on Resolve version, license, page state, and audio content.",
             "transcription_subtitles": "Transcription and subtitle generation can be asynchronous and may require installed AI components.",
-            "audio_property_writes": "Some item types expose audio properties as read-only or reject writes despite returning readable values.",
+            "audio_property_writes": "Level/pan/EQ writes are not honoured: SetProperty('Volume'/'Gain') returns False and 'Pan' writes the video transform. AudioSyncOffset writes do work. safe_set_audio_properties returns a known_limitation block with the bake / Fairlight-preset workaround.",
             "auto_sync": "AutoSyncAudio depends on media content, channel layout, and selected sync settings.",
         },
         "unsupported": {
@@ -8899,6 +8902,61 @@ def _probe_audio_item(tl, p: Dict[str, Any]):
     return _timeline_item_audio_snapshot(item)
 
 
+_AUDIO_LEVEL_KEYS = {"Volume", "Level", "Gain", "AudioVolume", "Pan", "EQEnable", "EQEnabled"}
+
+
+def _audio_write_limitation(written: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Guidance for an audio level/pan/EQ write that Resolve will not honour.
+
+    `written` maps each requested key to whether SetProperty returned True.
+    `SetProperty` on a TimelineItem covers the *video* transform only.
+    'Volume'/'Level'/'Gain' returned False when measured live on 21.0.0, and
+    'Pan' is the video-transform key — it returns True while the audio pan
+    stays put. A caller who sees `write: false` (or a Pan write that
+    "succeeds" and changes nothing) has hit a missing feature, not a bad
+    value, and the way around it is a different task: bake the gain into the
+    media, or drive Fairlight. Level/EQ keys are flagged only when the write
+    failed, so a build that honours them is not contradicted; Pan is always
+    flagged, because its success is the misleading case.
+    """
+    hit = sorted({
+        k for k, ok in written.items()
+        if k in _AUDIO_LEVEL_KEYS and (k == "Pan" or not ok)
+    })
+    if not hit:
+        return None
+    entry = next(iter(lookup_api_truth("Fairlight audio levels")), None)
+    out = {
+        "keys": hit,
+        "reason": "no_api_write_path",
+        "explanation": (
+            "Resolve's scripting API cannot set audio clip or track level, pan, "
+            "EQ, or automation. SetProperty writes the video transform only: "
+            "'Volume'/'Level'/'Gain' return False, and 'Pan' is the video "
+            "transform key so it returns True while the audio pan is unchanged."
+        ),
+        "workarounds": [
+            "Bake the level into a rendered copy of the source (ffmpeg "
+            "volume=NdB, plus afade / atrim for fades and trims) and import "
+            "that — the level is then part of the file.",
+            "For a repeatable whole mix (Resolve 20.2.2+; the preset methods "
+            "do not exist on 19.x), save it once as a Fairlight preset in "
+            "the Resolve UI, then apply it per timeline with "
+            "project_settings apply_fairlight_preset "
+            "(names from resolve_control get_fairlight_presets).",
+            "Set individual faders / pan / EQ on the Fairlight page by hand.",
+        ],
+        "ledger_verified_on": _API_TRUTH_VERIFIED_ON,
+    }
+    if entry:
+        out["ledger"] = {
+            "symbol": entry.get("symbol"),
+            "reality": entry.get("reality"),
+            "recommended": entry.get("recommended"),
+        }
+    return out
+
+
 def _safe_set_audio_properties(tl, p: Dict[str, Any]):
     item, err = _audio_item_from_params(tl, p)
     if err:
@@ -8938,7 +8996,18 @@ def _safe_set_audio_properties(tl, p: Dict[str, Any]):
                 row["restore"] = False
                 row["restore_error"] = str(exc)
         results[key] = row
-    return {"success": all(row.get("write") for row in results.values()), "results": results}
+    success = all(row.get("write") for row in results.values())
+    out = {"success": success, "results": results}
+    # 'Volume' never writes and 'Pan' moves the video transform, not the audio
+    # pan — so a bare {"write": false} (or a Pan that "succeeds" inertly) leaves
+    # the caller guessing. Attach the ledger entry and the bake / preset route
+    # whenever one of those keys was in play.
+    limitation = _audio_write_limitation(
+        {k: row.get("write") for k, row in results.items()}
+    )
+    if limitation:
+        out["known_limitation"] = limitation
+    return out
 
 
 def _voice_isolation_capabilities(tl, p: Dict[str, Any]):
@@ -13530,6 +13599,106 @@ def _safe_import_media(mp, p: Dict[str, Any]):
         _restore_current_folder(mp, previous)
 
 
+def _import_bounded_media(mp, ms, p: Dict[str, Any]):
+    """Create one bounded Media Pool item through MediaStorage.
+
+    Resolve's AddItemListToMediaPool itemInfo form is the public scripting API
+    for this operation. ``media_storage.import_to_pool(item_infos)`` passes its
+    ``{media, startFrame, endFrame}`` maps straight through; this wrapper adds
+    destination-folder scoping, naming, and created-item readback. ``start_frame``
+    and ``end_frame`` are passed unchanged as Resolve's ``startFrame`` and
+    ``endFrame`` values; this wrapper does not infer or compensate for end-frame
+    inclusivity. It imports into the *current* folder, so this helper deliberately
+    scopes and restores that UI state around the one API call.
+    """
+    source_path = p.get("source_path")
+    if not isinstance(source_path, str) or not source_path:
+        return _err("source_path must be a non-empty string", category="invalid_input")
+    if not os.path.isabs(source_path):
+        return _err("source_path must be an absolute path", category="invalid_input")
+    path_err = _path_error(source_path, must_be_file=True)
+    if path_err:
+        return _err(path_err, category="invalid_input")
+
+    frames = {}
+    for key in ("start_frame", "end_frame"):
+        value = p.get(key)
+        if isinstance(value, bool) or not isinstance(value, int):
+            return _err(f"{key} must be an integer", category="invalid_input")
+        frames[key] = value
+    if frames["start_frame"] < 0:
+        return _err("start_frame must be greater than or equal to 0", category="invalid_input")
+    if frames["end_frame"] < frames["start_frame"]:
+        return _err("end_frame must be greater than or equal to start_frame", category="invalid_input")
+
+    destination_folder = p.get("destination_folder")
+    if not isinstance(destination_folder, str) or not destination_folder:
+        return _err("destination_folder must be a non-empty Media Pool folder path", category="invalid_input")
+    if not _navigate_folder(mp, destination_folder):
+        return _err(f"Target folder not found: {destination_folder}",
+                    code="FOLDER_NOT_FOUND", category="invalid_input",
+                    remediation=_FOLDER_ID_REMEDIATION)
+
+    name = p.get("name")
+    if not isinstance(name, str) or not name.strip():
+        return _err("name must be a non-empty string", category="invalid_input")
+
+    previous, folder_err = _set_current_folder_temporarily(mp, destination_folder)
+    if folder_err:
+        return folder_err
+    try:
+        item_info = {
+            "media": source_path,
+            "startFrame": frames["start_frame"],
+            "endFrame": frames["end_frame"],
+        }
+        try:
+            items = ms.AddItemListToMediaPool([item_info])
+        except Exception as exc:
+            return _err(f"AddItemListToMediaPool failed: {exc}")
+        if not isinstance(items, list) or len(items) != 1:
+            return _err(
+                "Bounded import must return exactly one MediaPoolItem",
+                code="BOUNDED_IMPORT_ITEM_COUNT_MISMATCH",
+                category="resolve_api_failed",
+                state={"returned_item_count": len(items) if isinstance(items, list) else None},
+            )
+        item = items[0]
+        try:
+            renamed = bool(item.SetName(name))
+        except Exception as exc:
+            return _err(
+                f"Failed to rename bounded MediaPoolItem: {exc}; the item exists with Resolve's default name",
+                state={"item": _media_pool_item_summary(item)},
+            )
+        if not renamed:
+            return _err(
+                "Failed to rename bounded MediaPoolItem; the item exists with Resolve's default name",
+                state={"item": _media_pool_item_summary(item)},
+            )
+
+        properties, _ = _safe_clip_call(item, "GetClipProperty", "")
+        range_property_keys = (
+            "File Path", "FPS", "Frames", "Duration", "Start TC", "End TC",
+            "Sub Clip", "SubClip", "Is Sub Clip", "IsSubClip", "Is Subclip",
+        )
+        bounded_import_properties = {
+            key: properties[key]
+            for key in range_property_keys
+            if isinstance(properties, dict) and properties.get(key) not in (None, "")
+        }
+        return _ok(
+            source_path=source_path,
+            start_frame=frames["start_frame"],
+            end_frame=frames["end_frame"],
+            destination_folder=destination_folder,
+            item=_media_pool_item_summary(item),
+            bounded_import_properties=bounded_import_properties,
+        )
+    finally:
+        _restore_current_folder(mp, previous)
+
+
 def _safe_import_sequence(mp, p: Dict[str, Any]):
     pattern = p.get("FilePath") or p.get("file_path") or p.get("pattern")
     if not pattern:
@@ -21438,6 +21607,14 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
         — image sequences: params.clip_infos is a list of
           {FilePath, StartIndex, EndIndex} dicts (PascalCase keys per Resolve docs).
           Example: [{"FilePath": "frame_%03d.dpx", "StartIndex": 1, "EndIndex": 100}]
+      import_bounded_media(source_path, start_frame, end_frame, destination_folder, name)
+        -> {success, source_path, start_frame, end_frame, destination_folder, item,
+            bounded_import_properties}
+        — creates one bounded Media Pool item through
+          MediaStorage.AddItemListToMediaPool([{media, startFrame, endFrame}]).
+          start_frame/end_frame pass through unchanged as raw Resolve API values;
+          observed range semantics are reported from the created item properties.
+          destination_folder must already exist; the previous current folder is restored.
       delete_clips(clip_ids) -> {success}
         DESTRUCTIVE. Removes clips from the Media Pool (does not touch source files).
         An id matching no clip fails the whole call (CLIP_NOT_FOUND) rather than
@@ -21752,6 +21929,14 @@ def media_pool(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str
                 return _err("Provide paths (simple) or clip_infos (image sequences)")
             result = mp.ImportMedia(paths)
         return {"imported": len(result) if result else 0}
+    elif action == "import_bounded_media":
+        # _get_mp() returns the ProjectManager as its first value, not the
+        # Resolve application object. MediaStorage belongs to Resolve.
+        resolve = get_resolve()
+        ms = resolve.GetMediaStorage() if resolve else None
+        if not ms:
+            return _err("Failed to get MediaStorage")
+        return _import_bounded_media(mp, ms, p)
     elif action == "delete_clips":
         clips, clips_err = _clips_from_ids(root, p["clip_ids"], verb="deleted")
         if clips_err:
@@ -21887,7 +22072,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, ["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])
+    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","import_bounded_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])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -25896,7 +26081,10 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
       audio_capabilities() -> {supported, partially_supported, unsupported}
       probe_audio_item(track_type?, track_index?, item_index?) -> {summary, audio_properties, source_audio_mapping}
       probe_audio_track(track_index?) -> {track_count, enabled, locked, sub_type, voice_isolation}
-      safe_set_audio_properties(properties, restore?, dry_run?, track_type?, track_index?, item_index?) -> {success, results}
+      safe_set_audio_properties(properties, restore?, dry_run?, track_type?, track_index?, item_index?) -> {success, results, known_limitation?}
+        — Volume/Pan/EQ writes are not honoured by Resolve's API; a request for
+          any of them returns `known_limitation` with the bake / Fairlight-preset
+          workaround. AudioSyncOffset writes do work.
       audio_mix_capability_report(...) -> {capabilities, mix_recommendations}
       voice_isolation_capabilities(track_index?, track_type?, item_index?) -> {timeline_track, item}
       audio_mapping_report(clip_ids?) -> {timeline_items, media_pool_items}
@@ -26975,7 +27163,10 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
       get_composite(...) -> {Opacity, CompositeMode}
       set_composite(Opacity?, CompositeMode?, ...) -> {success}
       get_audio(...) -> {Volume, Pan, AudioSyncOffset, ...}
-      set_audio(Volume?, Pan?, ...) -> {success}
+      set_audio(Volume?, Pan?, ...) -> {success, known_limitation?}
+        — Resolve ignores Volume/Pan/EQ writes on audio; those return a
+          `known_limitation` block (bake gain into the media, or apply a
+          Fairlight preset). AudioSyncOffset / AudioSyncOffsetIsManual do work.
       get_keyframes(property, ...) -> {property, count, keyframes}
       add_keyframe(property, frame, value, ...) -> {success}
       modify_keyframe(property, frame, new_value?, new_frame?, ...) -> {success}
@@ -27210,7 +27401,15 @@ def timeline_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[
         for k, v in p.items():
             if k in valid:
                 results[k] = bool(item.SetProperty(k, v))
-        return _ok(**results) if results else _err(f"Specify one or more of: {', '.join(sorted(valid))}")
+        if not results:
+            return _err(f"Specify one or more of: {', '.join(sorted(valid))}")
+        out = _ok(**results)
+        # Volume/Pan writes go nowhere on audio (see _audio_write_limitation);
+        # AudioSyncOffset does work, so only flag when a level/pan key was asked.
+        limitation = _audio_write_limitation(results)
+        if limitation:
+            out["known_limitation"] = limitation
+        return out
 
     # ── Keyframes ──
     elif action == "get_keyframes":

package/src/utils/destructive_hook.py

@@ -123,6 +123,7 @@ DESTRUCTIVE_ACTIONS_BY_TOOL: Dict[str, FrozenSet[str]] = {
         "setup_multicam_timeline",
         "create_multicam_clip",
         "create_stereo_clip",
+        "import_bounded_media",
         "auto_sync_audio",
         "set_clip_marks",
         "clear_clip_marks",

package/src/utils/execution_lifecycle.py

@@ -236,6 +236,8 @@ class RiskClassificationHook(LifecycleHook):
         ("media_pool", "create_timeline"),
         ("media_pool", "create_timeline_from_clips"),
         ("media_pool", "create_stereo_clip"),
+        # Adds one bounded item; the source and existing pool contents remain intact.
+        ("media_pool", "import_bounded_media"),
         # Per-item display properties: set them back and the item is as it was.
         ("timeline_item", "set_clip_enabled"),
         ("timeline_item", "set_name"),