davinci-resolve-mcp

Category: Data & AI | Uploader: samuelgursky | Downloads: 0 | Version: v1.0（Latest）
This document gives AI assistants the context needed to use the DaVinci Resolve
Changelog: Source: GitHub https://github.com/samuelgursky/davinci-resolve-mcp
Directory Structure

Current level: tree/main/docs/
📁 authoring/
- 📄 fuse-dctl-authoring.md 11.9 KB
- 📄 script-plugin-authoring.md 8.3 KB
📁 guides/
- 📄 color-decision-guide.md 16.2 KB
- 📄 editorial-decision-guide.md 4.9 KB
- 📄 media-analysis-guide.md 16.5 KB
- 📄 multicam-setup-guide.md 4.9 KB
📁 integrations/
- 📄 workflow-integrations.md 5.7 KB
📁 kernels/
- 📄 audio-fairlight-kernel.md 4.1 KB
- 📄 color-grade-kernel.md 5.1 KB
- 📄 extension-authoring-kernel.md 4.8 KB
- 📄 fusion-composition-kernel.md 4.6 KB
- 📄 media-pool-ingest-kernel.md 7.9 KB
- 📄 project-lifecycle-kernel.md 6.2 KB
- 📄 README.md 4.3 KB
- 📄 render-deliver-kernel.md 4.6 KB
- 📄 review-annotation-kernel.md 4.7 KB
- 📄 timeline-conform-interchange-kernel.md 5.0 KB
- 📄 timeline-edit-kernel.md 6.6 KB
📁 notes/
- 📄 codec-plugin-notes.md 5.2 KB
- 📄 dctl-notes.md 8.3 KB
- 📄 fusion-template-notes.md 5.9 KB
- 📄 lut-notes.md 4.4 KB
- 📄 openfx-notes.md 5.2 KB
📁 process/
- 📄 release-process.md 4.2 KB
📁 reference/
- 📄 api-coverage.md 30.3 KB
- 📄 resolve_scripting_api.txt 98.6 KB
📄 contributing.md 4.5 KB
📄 install.md 5.4 KB
📄 README.md 2.8 KB
📄 SKILL.md 53.5 KB
SKILL.md

# DaVinci Resolve MCP Server — AI Skill Reference

This document gives AI assistants the context needed to use the DaVinci Resolve
MCP server effectively. It covers the tool landscape, page prerequisites,
common workflow patterns, error recovery, and known gotchas.

---

## What This Server Does

The DaVinci Resolve MCP server bridges AI assistants to DaVinci Resolve Studio
via its official Scripting API. You can control every aspect of a post-production
session — projects, timelines, clips, color grading, Fusion compositions, audio,
render queues, and more — through natural language.

DaVinci Resolve must be running with **Preferences > General > "External scripting
using"** set to **Local**. The server auto-launches Resolve if it is not running,
but that first connection can take up to 60 seconds.

Workflow Integration plugins/scripts are a separate Resolve-hosted UI mechanism.
They are not required for this MCP server, but `docs/integrations/workflow-integrations.md`
summarizes when they are useful for optional in-Resolve panels, UIManager
scripts, and render callback companions.

OpenFX plugins are native C++ image-effect plugins, not an MCP control surface.
Use `docs/notes/openfx-notes.md` when diagnosing `insert_ofx_generator` failures or
discussing optional OFX plugin development.

LUT files are directly relevant to Color-page graph actions. Use
`docs/notes/lut-notes.md` when diagnosing `graph.set_lut` failures, validating `.cube`
files, or explaining `project_settings.refresh_luts`.

Fusion templates are relevant to Edit/Cut page insertion actions. Use
`docs/notes/fusion-template-notes.md` when diagnosing `insert_fusion_generator` or
`insert_fusion_title` failures, template paths, `.setting` files, or `.drfx`
bundles.

DCTL files are programmable color transforms/effects adjacent to LUT and OpenFX
workflows. Use `docs/notes/dctl-notes.md` when diagnosing `.dctl`/`.dctle` discovery,
ResolveFX DCTL plugin behavior, ACES DCTL IDT/ODT setup, or DCTL-as-LUT usage.

Codec plugins are native IO encode plugins that extend Deliver-page render
formats/codecs. Use `docs/notes/codec-plugin-notes.md` when diagnosing missing custom
render formats/codecs, `.dvcp.bundle` packaging, or IOPlugins install paths.

The `fuse_plugin`, `dctl`, and `script_plugin` compound tools (v2.5.0+) write
Fuse plugin source, DCTL files, and Lua/Python scripts into Resolve's install
directories. They are *authoring* tools — every other tool in this server wraps
Resolve's scripting API, while these three emit and install plugin/script
source. Status: lifecycle-verified in DaVinci Resolve Studio 20.3.2.9 for
MCP-marked install/read/list/remove, regular DCTL `refresh_luts`, ACES/Fuse
restart-required classification, Python installed-script execution, and
Python/Lua `run_inline`. Use `docs/kernels/extension-authoring-kernel.md` for the
kernel boundary map, `docs/authoring/fuse-dctl-authoring.md` for the Fuse + DCTL coverage
matrix, and `docs/authoring/script-plugin-authoring.md` for the script DSL spec and the
conversational-execution model.

Extension Authoring kernel actions (v2.16.0+) are exposed through
`script_plugin`:

- `extension_capabilities`
- `probe_fuse_lifecycle(name?, kind?, install?, cleanup?)`
- `probe_dctl_lifecycle(name?, kind?, category?, install?, refresh_luts?, cleanup?)`
- `probe_script_lifecycle(name?, language?, category?, install?, execute?, cleanup?)`
- `safe_install_extension(extension_type, name, source?|kind?, dry_run?)`
- `safe_remove_extension(extension_type, name, dry_run?)`
- `refresh_or_restart_required(extension_type, category?)`
- `extension_boundary_report(include_template_matrix?)`

Key behavioral notes for `script_plugin`:
- `run_inline(source, language)` runs ad-hoc Lua/Python in Resolve and returns
  stdout + result — use this for one-off conversational queries against the
  Resolve API instead of building+installing a script.
- `language` accepts `lua`, `py`, or the human-facing aliases `python` and
  `python3`.
- `execute(name, category, language)` runs an installed script; Python stdout
  and stderr are captured, while installed Lua execution can return false from
  the Python bridge even when install/read/list/remove worked.
- Lua scripts: `fusion.Execute()` from the Python bridge is a no-op in
  Resolve 20.x — `_run_inline_lua` works around this with `RunScript` against
  a temp file plus completion-sentinel polling on `app:SetData/GetData`.
- Fuse install path on macOS is `…/DaVinci Resolve/Fusion/Fuses/` (NOT
  `Support/Fusion/Fuses/` as the SDK doc lists). The MCP path helpers handle
  this; if you're staging files manually, use the path the implementation
  emits.
- Resolve picks up new scripts without a restart; new Fuses need a restart
  to register; new DCTLs need `project_settings(action='refresh_luts')`
  (regular LUT category) or a restart (ACES IDT/ODT category).

Tool metadata (v2.17.1+) includes MCP `ToolAnnotations` for read-only,
destructive, idempotent, and external-resource hints. Treat compound tool
annotations as conservative because a single compound tool may expose both probe
and mutation actions behind its `action` parameter. Continue to prefer
`safe_*`, `dry_run`, `probe_*`, `capabilities`, and `boundary_report` actions
before mutating Resolve state.

---

## Two Server Modes

| Mode | Entry point | Tool count | Use when |
|---|---|---|---|
| Compound (default) | `src/server.py` | 31 tools | Most workflows — keeps context lean |
| Granular (full) | `src/server.py --full` | 329 tools | Power users needing one tool per API method |

This skill document covers the **compound server** (the default). Each compound
tool accepts an `action` string and an optional `params` object.

The compound server also registers MCP prompts. Use `davinci_resolve_workflow`
as the compact operating brief, and use `analyze_media` as a slash-command style
entry point for read-only project, selected-clip, bin, or file analysis. The
Analyze Media prompt defaults to chat-context visual analysis when the MCP
client supports sampling/image messages, while allowing `include_visuals=false`
for technical-only or privacy-sensitive runs. It also encodes session-only
defaults, optional transcription, and finished-video editorial guardrails.

---

## Editorial Memory And Decision-Making

When the user asks for cutting, pacing, story shape, suspense, comedy timing, or
tonal reframing, operate like an editor, not just a metadata scanner. Use
`docs/guides/editorial-decision-guide.md` as the project-owned craft reference. The
short version: emotion and story come first, then clarity, rhythm, eye trace,
screen geography, continuity, and coverage variety.

Before analyzing or rebuilding anything, check whether the active project already
contains useful evidence:

- `media_analysis(action="summarize")`
- `media_analysis(action="get_report")` when a manifest or report path is known
- `timeline(action="list")`
- `timeline(action="get_current")`
- `timeline(action="probe_timeline_structure")`
- `timeline(action="source_range_report")`
- `timeline_markers(action="get_all")`
- `media_analysis(action="review_timeline_markers")` when marker imagery matters

Reuse prior analysis unless it is stale, incomplete, or missing the modality the
user is asking for. For example, do not re-run visual analysis just because the
edit task is new if a current report already has keyframes, motion variance, and
usable visual descriptions. Add transcription, chat-context vision, marker
review, or source range checks only when that missing evidence changes the
decision. Use `force_refresh=true` only when the user asks for a fresh read or
when cache signatures show the source, prompt, depth, or requested modality has
changed.

For finished-video editorial work, scene detection and motion variance are
guardrails, not story. Use them to avoid black frames, flash frames, corrupt
ranges, and accidental cut points. Let transcript, sound events, complete
thoughts, reactions, and decisive visual frames drive the actual edit.

After creating or modifying a timeline variant, do a second pass before calling
the work done:

- `timeline(action="detect_gaps_overlaps")`
- `timeline(action="source_range_report")`
- `timeline_markers(action="get_thumbnail_image")` at important markers and cuts
- Compare each marker name against the Resolve-rendered frame; revise the marker
  or edit if the image contradicts the plan.

Do not depend on personal, external, or workstation-specific editorial context.
For this project, keep the editorial craft reference self-contained in
`docs/guides/editorial-decision-guide.md` and keep this `SKILL.md` focused on
operational use of the MCP.

---

## Color Memory And Decision-Making

When the user asks for color correction, shot matching, look development, LUTs,
DCTLs, DRX grades, Gallery stills, or color-group workflows, use
`docs/guides/color-decision-guide.md` as the project-owned color reference.

Be explicit about the API boundary:

- Directly creatable/control surfaces: CDL values on an existing node, grade
  versions, color-group assignment, LUT assignment on existing nodes, node
  enable/cache state, LUT/DCTL assets, Gallery still import/export, and grade
  copy/export helpers.
- Opaque full-grade surfaces: copied grades, imported/exported `.drx` stills,
  and manually built Resolve node graphs. These can carry full grades, but the
  MCP applies or copies them as packages.
- Not directly creatable from structured params: new node trees, Lift/Gamma/Gain
  wheel values, log/HDR palette values, curves, qualifiers, power windows,
  tracking, Color Warper, and detailed ResolveFX/OFX parameter edits.

For safe color work, start with `timeline_item_color(action="grade_boundary_report")`,
`timeline_item_color(action="grade_version_snapshot")`,
`timeline_item_color(action="probe_node_graph")`, and a Resolve-rendered frame
reference for the target shot or shots. Use thumbnails, contact sheets, Gallery
stills, marker frames, or existing visual analysis reports before writing a
grade, and cite the inspected frames in the response. When the API can safely
provide them, compare matched untreated/bypass, current, and after frames at the
same timecodes, then restore the previous active version or node-enabled state
after any temporary bypass capture. Treat untreated frames as diagnostic
evidence, not as permission to discard an existing creative grade.

Prefer `safe_set_cdl` for small reversible primary corrections. Use DRX/stills
or grade copy only when the user accepts whole-grade replacement/transfer
semantics. Use DCTL/LUT authoring only for reusable mathematical transforms, not
as a substitute for hand-built windows, qualifiers, or tracked secondaries. Do
not apply blind/global grades unless the user explicitly asks for that. When the
user asks to build on or adjust an existing grade, preserve the current
grade/version as the starting point, create or switch to a recoverable
adjustment version, and apply only incremental changes through supported
controls. Do not reset grades, replace graphs, or apply DRX/copy-grade
whole-grade artifacts unless replacement or transfer semantics are explicitly
accepted. Distinguish Resolve's default one-node graph from an existing creative
grade; only describe a creative grade when active tools, LUTs, or other grade
state are present.

For sequence-wide looks, prefer a duplicated timeline, batch creation of
reference/current/look versions across all target clips, and one bulk Resolve
script for repeated version, group, or CDL operations. Use color groups for shared
scene-level intent only when they fit the work: group pre-clip for shared
normalization, clip versions for shot-specific matching, and group post-clip for
the creative look. Sampling can guide a first pass, but final handoff should
state the reviewed scope; short sequences should be checked shot by shot.

---

## Page Context Requirements

DaVinci Resolve is a page-based application. Certain operations only work on
specific pages. Always confirm or switch pages before calling page-sensitive tools.

| Operation category | Required page | How to switch |
|---|---|---|
| Color grading, node graphs, CDL | Color | `resolve_control(action="open_page", params={"page": "color"})` |
| Gallery stills export, `grab_and_export` | Color, Gallery panel open | `resolve_control` + open Gallery panel in Workspace menu |
| Fusion compositions (page comp) | Fusion | `resolve_control(action="open_page", params={"page": "fusion"})` |
| Timeline editing, track operations | Edit or Cut | `resolve_control(action="open_page", params={"page": "edit"})` |
| Fairlight audio | Fairlight | `resolve_control(action="open_page", params={"page": "fairlight"})` |
| Render / deliver | Deliver | `resolve_control(action="open_page", params={"page": "deliver"})` |
| Media import, storage browsing | Media | `resolve_control(action="open_page", params={"page": "media"})` |

When a tool returns an unexpected `False` or an error about context, check whether
you are on the correct page first.

---

## Tool Map

### App Control

**`resolve_control`** — App-level operations.

Key actions:
- `launch` — connect to or start Resolve; call this first if any tool returns a
  "Not connected" error
- `get_version` — returns `{product, version, version_string}`
- `get_page` / `open_page(page)` — read or switch the active page
- `get_keyframe_mode` / `set_keyframe_mode(mode)`
- `get_fairlight_presets` — Resolve 20.2.2+; returns available Fairlight
  preset names
- `quit` — terminates Resolve (destructive; confirm with user first)

**`layout_presets`** — Save, load, export, import, delete UI layout presets.

**`render_presets`** — Import and export render and burn-in presets.

---

### Project Management

**`project_manager`** — CRUD on projects.

Key actions: `list`, `get_current`, `create(name, media_location_path?)`,
`load(name)`, `save`, `close`,
`delete(name)`, `import_project(path)`, `export_project(name, path)`, `archive`,
`restore`

Project / Database / Archive kernel actions (v2.15.0+) add guarded project
lifecycle, settings, database, preset, and archive boundary helpers:

- `project_capabilities`
- `probe_project_lifecycle`
- `probe_project_settings(keys?, try_write?, dry_run?)`
- `safe_project_create(name, media_location_path?, dry_run?)`
- `safe_project_export(name, path, with_stills_and_luts?, dry_run?)`
- `safe_project_import(path, name, dry_run?)`
- `safe_project_archive(name, path, src_media=false, render_cache=false, proxy_media=false, dry_run?)`
- `safe_project_restore(path, name, dry_run?)`
- `safe_project_delete(name, close_current?, dry_run?)`
- `safe_set_project_settings(settings, restore?, dry_run?)`
- `project_settings_snapshot(name?)`
- `database_capabilities`
- `safe_set_current_database(db_info, dry_run?, allow_switch?)`
- `preset_lifecycle_probe`
- `project_boundary_report`

Safe project actions require `_mcp_` names and temp paths by default. Database
switching dry-runs by default because Resolve closes open projects when
switching databases. Archive source media/cache/proxy flags are rejected unless
explicitly opted in.

**`project_manager_folders`** — Navigate project folders.

Key actions: `list`, `get_current`, `create(name)`, `open(name)`, `goto_root`,
`goto_parent`

**`project_manager_database`** — Switch databases.

Key actions: `get_current`, `list`, `set_current(db_info)`

**`project_manager_cloud`** — Cloud projects (requires Resolve cloud
infrastructure; most users will not have this).

**`project_settings`** — Project metadata, settings, color groups, and misc
operations on the open project.

Key actions: `get_name`, `set_name(name)`, `get_setting(name?)`,
`set_setting(name, value)`, `get_color_groups`, `add_color_group(name)`,
`delete_color_group(name)`, `export_frame_as_still(path)`,
`load_burnin_preset(name)`, `insert_audio(media_path, ...)`,
`apply_fairlight_preset(preset_name)`

---

### Media

**`media_storage`** — Browse mounted volumes and import files.

Key actions: `get_volumes`, `get_subfolders(path)`, `get_files(path)`,
`import_to_pool(items)` — `items` is a list of file path strings

**`media_pool`** — Full Media Pool management.

Key actions: `get_root_folder`, `get_current_folder`, `set_current_folder(path)`,
`add_subfolder(name)`, `create_timeline(name)`, `import_timeline(path, options?)`,
`import_media(paths)`, `delete_clips(clip_ids)`, `move_clips(clip_ids, target_path)`,
`setup_multicam_timeline(name, clip_ids|angles, sync_mode?, include_audio?, dry_run?)`,
`get_selected`, `set_selected(clip_id)`, `export_metadata(path, clip_ids?)`

Media Pool / Ingest kernel actions (v2.8.0+) add safer agent-facing workflows:
`ingest_capabilities`, `probe_media_pool`, `probe_ingest_item`,
`safe_import_media`, `safe_import_sequence`, `safe_import_folder`,
`organize_clips`, `copy_metadata`, `normalize_metadata`,
`probe_clip_properties`, `safe_relink`, `safe_unlink`, `link_proxy_checked`,
`link_full_resolution_checked`, `set_clip_marks`, `clear_clip_marks`,
`copy_clip_annotations`, `setup_multicam_timeline`, and
`media_pool_boundary_report`. See
`docs/kernels/media-pool-ingest-kernel.md` for the live-tested support map.

`setup_multicam_timeline` is a helper, not a native multicam API wrapper. It
creates a source-safe stacked prep timeline with one angle per video track,
optional matching audio tracks, and `stack_start`, `source_timecode`, or
explicit `record_frame` placement. Native multicam clip creation, angle
switching, and flattening remain Resolve UI workflows; see
`docs/guides/multicam-setup-guide.md`.

Note: `folder path` arguments use slash notation like `"Master/SubFolder"`.
`"Master"` or `"/"` refers to the root folder.

**`folder`** — Operations on a specific Media Pool folder.

Key actions: `get_clips(path?)`, `get_subfolders(path?)`, `export(path?, export_path)`,
`transcribe_audio(path?)`, `clear_transcription(path?)`

**`media_pool_item`** — Read/write clip metadata and properties. All actions
require a `clip_id` (the UUID returned by `GetUniqueId()`).

Key actions: `get_name`, `get_metadata(key?)`, `set_metadata(key, value)`,
`get_clip_property(key?)`, `set_clip_property(key, value)`, `get_clip_color`,
`set_clip_color(color)`, `link_proxy(proxy_path)`, `replace_clip(path)`,
`set_name(name)`, `link_full_resolution_media(path)`,
`replace_clip_preserve_sub_clip(path)`, `monitor_growing_file`,
`transcribe_audio`, `get_audio_mapping`, `get_mark_in_out`, `set_mark_in_out`

**`media_pool_item_markers`** — Markers and flags on clips in the Media Pool.
All actions require a `clip_id`.

Key actions: `add(frame, color, name, note, duration)`, `get_all`, `delete_by_color(color)`,
`delete_at_frame(frame)`, `add_flag(color)`, `get_flags`, `set_name(name)`

**`media_analysis`** — Project-scoped media intelligence and guarded metadata publishing.

Media Analysis and editorial-assist actions (v2.17.0+) add source-safe planning,
report reuse, session-only execution, chat-context visual review, and
timeline-level editorial helpers.

Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
`analyze_file`, `analyze_clip`, `analyze_bin`, `analyze_project`,
`detect_sync_events`, `add_sync_event_markers`, `publish_clip_metadata`,
`summarize`, `get_report`, `review_timeline_markers`, and `cleanup_artifacts`.
The tool never installs
dependencies and validates that outputs stay under
`davinci-resolve-mcp-analysis` project roots rather than beside source media.
Executed file/clip analysis defaults to session-only: scratch artifacts are
removed after structured reports are returned to the MCP response. `persist=true`
keeps reports under the project analysis root, and `keep_artifacts=true`
preserves a session scratch run for inspection. `quick` uses ffprobe metadata;
`standard` adds ffmpeg read-through checks, motion/variance scoring, analysis
keyframes, and sidecar reports.
By default, planning checks the active project's analysis root for existing
reports and marks matching clips `skip_execution=true` when those reports already
contain the requested technical, motion, transcription, and vision layers.
Reports include cache signatures with source stat, depth, frame budget, prompt
hash, and requested modalities. Use `force_refresh=true` for a fresh read,
`max_report_age_days` for freshness limits, and `reuse_policy="fresh"` when
unsigned older reports should not be reused. Pass `reuse_existing=false` only
when the user explicitly wants to ignore memory.
Transcription requires explicit opt-in. The `analyze_media` prompt opts into
visual analysis by default and uses `vision.provider="chat_context"` when the
MCP client supports sampling; pass `include_visuals=false` to opt out. For
direct `media_analysis` tool calls, set `vision.enabled=true` explicitly when
visual interpretation is needed. Sampled frames are sent to the current
chat/sampling model and the response is stored in the default structured JSON
shape. If chat-context vision is unavailable, continue with technical/motion
analysis and ask whether the user wants setup steps or a no-visual run. The
local mock providers are for tests and do not send frames off-machine.
Use `detect_sync_events` before multicam setup, deliverable QC, or single-camera
sync review when the user needs likely 2-pop or slate-clap locations. It reads
source audio through FFmpeg/FFprobe only, returns advisory frames/timecodes and
per-file `record_offset` suggestions, and never installs FFmpeg automatically.
It also returns marker suggestions; only call `add_sync_event_markers` after the
user explicitly approves marker writes, and pass `confirm=true`.
Use `publish_clip_metadata` when the user wants analysis to become searchable
inside Resolve. It analyzes or reuses reports, proposes field-specific merges
for `Description`, `Comments`, `Keywords`, `People`, and optional slate-derived
fields, stores provenance in third-party metadata, defaults to `dry_run=true`,
and writes Resolve metadata only when called with `confirm=true`.
`review_timeline_markers` creates a labeled
Resolve-rendered marker contact sheet plus JSON sidecar, and can request
chat-context vision for marker/frame mismatch review.

Before calling `analyze_*`, prefer `summarize` and `get_report` to discover
existing reports for the active project. If reports exist, use them as the
working memory for edit decisions and only request fresh analysis when a missing
layer changes the decision. If a user is
making story or audio-spine decisions and transcription is available but disabled,
tell them that transcript analysis may materially improve the edit instead of
silently skipping it. Resolve-native transcription changes project state; use it
only when that mutation is intentional.

---

### Timelines

**`timeline`** — Timeline operations: tracks, clips, import/export, generators.

Key actions:
- `list` — all timelines in the project
- `get_current` — current timeline info
- `set_current(index)` — switch timeline by 1-based index
- `get_track_count(track_type)` — track_type: `"video"`, `"audio"`, `"subtitle"`
- `add_track(track_type, sub_type?)` / `delete_track(track_type, index)`
- `get_items(track_type, index)` — items on a track
- `delete_clips(clip_ids, ripple?)` — IDs are unique IDs from `get_items`
- `duplicate_clips(clip_ids?, selected?, target_track_index?, track_offset?, placement?, record_frame?, record_frame_offset?, copy_properties?, include_linked?)` —
  duplicate existing video timeline items by re-appending the same Media Pool
  item with the same source trim; `selected=True` uses Resolve's selected/current
  item when available, `placement` supports `"same_time"`, `"offset"`,
  `"at_playhead"`, `"track_above"`, `"after_source"`, and `"next_gap"`, and
  `include_linked=True` duplicates linked audio and restores link state.
  `copy_properties` can copy `transform`, `crop`, `composite`, `audio`,
  `retime`, `dynamic_zoom`, `scaling`, `stabilization`, `clip_color`,
  `markers`, `flags`, `enabled`, `cache`, `voice_isolation`, `fusion`,
  `grades`, `takes`, and `keyframes`; `transitions` is accepted but reported
  unsupported because Resolve's public scripting API does not expose transition
  cloning. `copy_keyframes=True` adds the `keyframes` group.
- `copy_clips(...)` / `move_clips(...)` — same safe append path; `move_clips`
  deletes successfully duplicated source items afterward
- `copy_range` / `duplicate_range` — copy exact video/audio source segments
  from `start_frame`/`end_frame` or mark in/out to `record_frame`
- `overwrite_range` — delete whole destination overlaps, then copy the exact
  range segment
- `lift_range` — delete whole items in a range; partial overlaps require
  `allow_partial_item_delete=True` because Resolve does not expose a safe
  partial lift primitive here
- `story_spine_report` — read markers, source ranges, and audio/video structure
  into an editor-facing beat report
- `create_variant_from_ranges(name, ranges, markers?, cdl?, dry_run?)` — create
  a guarded timeline variant from declarative source ranges, optional markers,
  transforms, and CDL
- `bulk_set_item_properties(ops, dry_run?, readback?)` — apply transforms,
  crop/composite/audio/property groups to many timeline items in one call
- `apply_look_to_items(target_ids, cdl?|copy_from_item_id?, dry_run?)` — apply a
  normalized CDL and/or copy a source grade to multiple video items
- `thumbnail_contact_sheet` / `marker_thumbnail_review` — sample Resolve-rendered
  thumbnails under the project analysis root for visual verification
- `edit_kernel_capabilities` — report supported, partially supported, and
  unsupported timeline edit kernel behavior
- `probe_edit_kernel_item(clip_ids? selected? timeline_item?)` — read-only
  capability/property probe for timeline items, including available item
  methods, `GetProperty()` values, known property keys, keyframe counts, and
  linked item summaries
- `title_property_scan(clip_id|timeline_item_id|timeline_item)` — inspect
  undocumented Edit-page title/generator `TimelineItem.GetProperty()` keys
- `set_title_text(clip_id|..., text, property_key?, as_styled_xml?, try_plain_first?, try_heuristic_keys?, readback?)`
  / `bulk_set_title_text(ops, ...)` — update title text via explicit or scanned
  keys when the current Resolve build accepts the `SetProperty()` write
- `export(path, type, subtype?)` — type: `"AAF"`, `"EDL"`, `"FCPXML"`, `"DRT"`, etc.
- `insert_generator(name)`, `insert_title(name)`, `insert_fusion_title(name)`
- `get_mark_in_out`, `set_mark_in_out(mark_in, mark_out, type?)`
- `duplicate(name?)` — duplicate the current timeline
- `get_voice_isolation_state(track_index)` / `set_voice_isolation_state`
- `extract_source_frame_ranges(handles?, gap_max?, skip_extensions?)` — return
  inclusive source frame ranges for current-timeline video clips, with fixed
  handles or gap-only auto handles when `handles=0`

Timeline Conform / Interchange kernel actions (v2.13.0+) add live-tested
structure, interchange, comparison, missing-media, and relink-planning helpers:

- `conform_capabilities`
- `probe_timeline_structure(track_types?, include_markers?, include_clip_properties?)`
- `detect_gaps_overlaps(track_types?, min_gap?)`
- `source_range_report(handles?, merge?)`
- `export_timeline_checked(path, format?|type?, subtype?, require_temp_path?, dry_run?)`
- `import_timeline_checked(path, options?, timeline_name?, import_source_clips?, require_temp_path?, dry_run?)`
- `compare_timelines(right_timeline_id?|right_timeline_index?|left_snapshot?, right_snapshot?)`
- `probe_interchange_roundtrip(format?, output_dir?, cleanup_imported?)`
- `detect_missing_media`
- `build_relink_plan(search_roots)`
- `conform_boundary_report`

Audio / Fairlight kernel actions (v2.14.0+) add live-tested audio state,
mapping, voice-isolation, sync, transcription, subtitle, and Fairlight boundary
helpers:

- `audio_capabilities`
- `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?)`
- `audio_mix_capability_report(...)`
- `voice_isolation_capabilities(track_index?, track_type?, item_index?)`
- `audio_mapping_report(clip_ids?)`
- `safe_auto_sync_audio(clip_ids|selected, settings?, dry_run?)`
- `transcription_capabilities(clip_ids?|selected?)`
- `subtitle_generation_probe(settings?, allow_generate?)`
- `fairlight_boundary_report`

**`timeline_markers`** — Markers and playhead on the current timeline.

Key actions: `add(frame|frame_id|timecode?, color?, name?, note?, duration?)`, `get_all`,
`get_current_timecode`, `set_current_timecode(timecode)`,
`get_current_video_item`, `get_thumbnail`, `get_thumbnail_image`

Review Annotation kernel actions (v2.10.0+) add a unified review layer across
timeline, timeline item, and media pool item scopes: `annotation_capabilities`,
`probe_annotations`, `normalize_marker_payload`, `copy_annotations`,
`move_annotations`, `sync_marker_custom_data`, `clear_annotations_by_scope`,
`export_review_report`, and `annotation_boundary_report`. See
`docs/kernels/review-annotation-kernel.md` for the live-tested scope and boundary map.

For `add`, omit `frame`/`timecode` to create the marker at the current playhead.
The compound tool accepts `frame`, `frame_id`, and `frameId` aliases.

Note: `get_thumbnail` returns raw pixel data from `GetCurrentClipThumbnailImage()`.
The dictionary includes `data` (raw bytes as a Python bytes-like object),
`format`, `width`, `height`, `noOfComponents`, and `depth`. This reflects the
current frame as rendered by Resolve — including any color grading or effects
applied — which is different from reading the source file directly.

Use `get_thumbnail_image` when the MCP client can display image content directly.
It converts the same Resolve thumbnail payload to PNG bytes without writing a
file to disk.

**`timeline_ai`** — AI/ML analysis on the current timeline.

Key actions: `create_subtitles(settings?)`, `detect_scene_cuts`,
`grab_still`, `grab_all_stills(source?)`, `analyze_dolby_vision`

---

### Timeline Items

Timeline items are identified by `track_type`, `track_index`, and `item_index`
(all default to `"video"`, `1`, `0` respectively — the first clip on the first
video track). Always retrieve item IDs via `timeline.get_items` before operating
on specific items.

**`timeline_item`** — Properties, transform, speed, audio, keyframes.

Key actions:
- `get_property(key?)` / `set_property(key, value)` — raw property access
- `get_name` / `set_name(name)`
- `get_duration`, `get_start`, `get_end`
- `get_retime` / `set_retime(process?, motion_estimation?)`
  - process: `"nearest"`, `"frame_blend"`, `"optical_flow"` (or 0–3)
  - motion_estimation: integer 0–6
- `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_voice_isolation_state` / `set_voice_isolation_state(state)` — Resolve
  20.1+; audio timeline items only
- `get_keyframes(property)`, `add_keyframe(property, frame, value)`,
  `modify_keyframe`, `delete_keyframe`, `set_keyframe_interpolation`
  - interpolation values: `"Linear"`, `"Bezier"`, `"EaseIn"`, `"EaseOut"`, `"EaseInOut"`
- `get_unique_id` — use this to get the ID for other tool calls
- `get_media_pool_item` — get the source clip from the Media Pool

**`timeline_item_markers`** — Markers, flags, clip color on timeline items.

**`timeline_item_fusion`** — Fusion comp management on timeline items.

Key actions: `add_comp`, `get_comp_count`, `get_comp_names`, `export_comp(path, index)`,
`import_comp(path)`, `delete_comp(name)`, `load_comp(name)`, `rename_comp`,
`get_cache_enabled`, `set_cache(value)` — value: `"Auto"`, `"On"`, `"Off"`

**`timeline_item_color`** — Color grading on timeline items. Requires Color page
for most operations.

Key actions:
- `set_cdl(cdl)` — cdl: `{NodeIndex, Slope, Offset, Power, Saturation}`
  - Slope/Offset/Power can be arrays `[R, G, B]` or strings like `"1.0 1.0 1.0"`
- `add_version(name, type?)`, `load_version(name, type?)`, `get_version_names(type?)`
  - type: `0` = local, `1` = remote
- `assign_color_group(group_name)`, `remove_from_color_group`
- `export_lut(type, path)`
- `reset_all_node_colors` — Resolve 20.2+; resets node colors for the active
  clip version
- `stabilize`, `smart_reframe`
- `create_magic_mask(mode)` — mode: `"F"` forward, `"B"` backward, `"BI"` bidirectional
  (requires DaVinci Neural Engine and Color page)

Color / Grade kernel actions (v2.11.0+) add safer grade inspection and
boundary helpers: `grade_capabilities`, `probe_grade_item`,
`probe_node_graph`, `safe_set_cdl`, `safe_copy_grade`, `safe_apply_drx`,
`safe_export_lut`, `grade_version_snapshot`, `grade_version_restore`,
`color_group_capabilities`, `gallery_capabilities`, and
`grade_boundary_report`. See `docs/kernels/color-grade-kernel.md` for the live-tested
support map, and `docs/guides/color-decision-guide.md` for the practical distinction
between direct API color controls and opaque full-grade artifacts.

**`timeline_item_takes`** — Take management.

Key actions: `add(clip_id, start_frame?, end_frame?)`, `get_count`,
`get_selected_index`, `select(index)`, `delete(index)`, `finalize`

---

### Gallery

**`gallery`** — Gallery album management.

Key actions: `get_still_albums`, `get_current_album`, `set_current_album(album_index)`,
`create_still_album`, `create_power_grade_album`

**`gallery_stills`** — Manage stills within an album. Requires Color page.

Key actions:
- `get_stills(album_index?)` — returns count
- `get_label(still_index)` / `set_label(still_index, label)`
- `import_stills(paths)` — paths to `.drx` files
- `export_stills(folder_path, prefix?, format?, album_index?)`
  - formats: `dpx`, `cin`, `tif`, `jpg`, `png`, `ppm`, `bmp`, `xpm`, `drx`
- `grab_and_export(folder_path, prefix?, format?, album_index?, cleanup?)` —
  grabs a still from the current frame and exports it in one atomic call.
  Returns `{files, format, folder, cleaned_up}` where each file entry includes
  `data_base64` for image files and `data` (text) for `.drx` grade files.
  `cleanup` defaults to `true` — files are deleted from disk after being inlined.
  Requires Color page with Gallery panel visible.
- `delete_stills(still_indices)`

---

### Node Graphs

**`graph`** — Node graph operations on timeline, timeline item, or color group.

The `source` parameter controls which graph you target:
- `"timeline"` (default) — the timeline node graph
- `"item"` — a specific timeline item (needs `track_type`, `track_index`, `item_index`)
- `"color_group_pre"` / `"color_group_post"` — group pre/post graphs (needs `group_name`)

Key actions: `get_num_nodes(source?)`, `set_lut(node_index, lut_path, source?)`,
`get_lut(node_index, source?)`, `get_node_label(node_index, source?)`,
`set_node_enabled(node_index, enabled, source?)`,
`apply_grade_from_drx(path, grade_mode?, source?)` — grade_mode: `0`=no keyframes,
`1`=source timecode aligned, `2`=start frames aligned,
`reset_all_grades(source?)`

**`color_group`** — Manage color groups.

Key actions: `list`, `get_name(group_name)`, `set_name(group_name, new_name)`,
`get_clips(group_name)`, `get_pre_clip_graph(group_name)`,
`get_post_clip_graph(group_name)`

---

### Fusion

**`fusion_comp`** — Fusion composition node graph operations.

Target a comp either from a timeline item (pass `clip_id`, `timeline_item_id`, or
`timeline_item={track_type, track_index, item_index}`) or from the active Fusion
page comp (omit timeline scope).

Key actions:
- `add_tool(tool_type, x?, y?, name?)` — common types: `Merge`, `Background`,
  `TextPlus`, `Transform`, `Blur`, `ColorCorrector`, `RectangleMask`,
  `EllipseMask`, `Tracker`, `MediaIn`, `MediaOut`, `Glow`, `DeltaKeyer`,
  `UltraKeyer`, `FilmGrain`, `CornerPositioner`
- `delete_tool(tool_name)`, `get_tool_list(type?)`, `find_tool(name)`
- `connect(target_tool, input_name, source_tool, output_name?)`
- `disconnect(tool_name, input_name)`
- `set_input(tool_name, input_name, value, time?)` /
  `get_input(tool_name, input_name, time?)`
- `get_inputs(tool_name)` / `get_outputs(tool_name)`
- `set_attrs(tool_name, attrs)` / `get_attrs(tool_name)`
- `add_keyframe(tool_name, input_name, time, value)`
- `get_comp_info`, `set_frame_range(start, end)`, `render`
- `start_undo(name?)` / `end_undo(keep?)`
- `bulk_set_inputs(ops)` — batch set inputs across multiple timeline item comps in
  one call; each op requires timeline scope plus `tool_name`, `input_name`, `value`

Fusion Composition kernel actions (v2.12.0+) add safer graph inspection and
mutation wrappers around the raw Fusion API:

- `fusion_graph_capabilities`
- `probe_fusion_comp(include_io?, max_tools?)`
- `probe_fusion_tool(tool_name, include_io?)`
- `safe_add_tool(tool_type, name?, dry_run?)`
- `safe_set_inputs(tool_name, inputs, readback?)`
- `safe_connect_tools(target_tool, input_name, source_tool, dry_run?)`
- `fusion_boundary_report(include_io?)`

---

### Render

**`render`** — Render pipeline: jobs, presets, formats, codecs.

Key actions: `add_job`, `list_jobs`, `delete_job(job_id)`, `delete_all_jobs`,
`start(job_ids?, interactive?)`, `stop`, `is_rendering`, `get_formats`,
`get_codecs(format)`, `set_format_and_codec(format, codec)`,
`get_resolutions(format, codec)`, `set_settings(settings)`,
`list_presets`, `load_preset(name)`, `save_preset(name)`,
`quick_export_presets`, `quick_export(preset, params?)`

Render / Deliver kernel actions (v2.9.0+) add planning and safety layers:
`render_capabilities`, `probe_render_matrix`, `probe_render_settings`,
`validate_render_settings`, `safe_set_render_settings`,
`prepare_render_job`, `render_job_lifecycle_probe`,
`quick_export_capabilities`, `safe_quick_export`, and
`export_render_boundary_report`. See `docs/kernels/render-deliver-kernel.md` for the
live-tested format/codec, settings, job, and Quick Export boundary map.

---

## Common Workflows

### 1. Connect and verify

```
resolve_control(action="launch")
resolve_control(action="get_version")
resolve_control(action="get_page")
```

Always call `launch` first in a new session. It is safe to call when Resolve is
already running.

### 2. Open a project and navigate timelines

```
project_manager(action="list")
project_manager(action="load", params={"name": "My Film"})
timeline(action="list")
timeline(action="set_current", params={"index": 2})
timeline(action="get_current")
```

### 3. Add clips to Media Pool and build a timeline

```
media_storage(action="get_volumes")
media_storage(action="import_to_pool", params={"items": ["/path/to/clip.mp4"]})
media_pool(action="get_current_folder")
media_pool(action="create_timeline", params={"name": "Assembly"})
media_pool(action="get_selected")
media_pool(action="append_to_timeline", params={"clip_ids": ["<uuid>", ...]})
media_pool(action="safe_import_sequence", params={
  "pattern": "/path/to/frames/shot_%04d.dpx",
  "start_index": 1001,
  "end_index": 1048,
  "target_folder": "Master/Plates"
})
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": [
  {"clip_id": "<uuid>", "start_frame": 0, "end_frame": 100, "record_frame": 1200, "track_index": 4}
]})
```

### 4. Inspect and annotate timeline items

```
timeline(action="get_items", params={"track_type": "video", "index": 1})
timeline(action="duplicate_clips", params={
  "clip_ids": ["<timeline-item-uuid>"], "target_track_index": 2, "record_frame_offset": 120
})
timeline(action="duplicate_clips", params={
  "selected": True,
  "placement": "track_above",
  "include_linked": True,
  "copy_properties": ["transform", "crop", "composite", "audio", "dynamic_zoom", "scaling", "stabilization", "clip_color", "markers", "enabled"],
  "copy_keyframes": True
})
timeline(action="probe_edit_kernel_item", params={"selected": True})
timeline(action="copy_range", params={
  "start_frame": 110, "end_frame": 130, "record_frame": 900,
  "track_types": ["video", "audio"], "target_track_index": 2
})
timeline_item(action="get_name", params={"track_type": "video", "track_index": 1, "item_index": 0})
timeline_item(action="get_property", params={"track_type": "video", "track_index": 1, "item_index": 0})
timeline_markers(action="add", params={"color": "Blue", "note": "Review this"})
timeline_item_markers(action="add", params={"frame": 100, "color": "Blue", "name": "Review", "note": "Check this", "duration": 1, "track_type": "video", "track_index": 1, "item_index": 0})
```

For an exhaustive live boundary map of the timeline edit kernel, run:

```
python3.11 tests/live_duplicate_clips_validation.py --output-dir /tmp/timeline-kernel-probe
```

The live harness first validates duplicate/range edit behavior, then runs the
exhaustive probe. It creates disposable projects with synthetic media, emits
JSON and Markdown reports, and classifies each API surface as `supported`,
`partially_supported`, `read_only`, `write_only_unverifiable`,
`version_or_page_dependent`, `unsupported`, `not_applicable`, or `error`.
See `docs/kernels/timeline-edit-kernel.md` for the maintained support map and current
Resolve API limitations.

For the Media Pool / Ingest boundary map, run:

```
python3.11 tests/live_media_pool_ingest_validation.py --output-dir /tmp/media-pool-ingest-probe
```

The harness creates a disposable project, generates synthetic video/audio/still
and image-sequence fixtures, probes safe import/metadata/annotation/link
helpers, writes JSON and Markdown reports, deletes the project, and removes the
generated media directory. See `docs/kernels/media-pool-ingest-kernel.md`.

For the Review Annotation boundary map, run:

```
python3.11 tests/live_review_annotation_validation.py --output-dir /tmp/review-annotation-probe
```

The harness creates a disposable project, generates synthetic video/audio media,
probes timeline, timeline item, and media pool item marker/flag/color/report
behavior, writes JSON and Markdown reports, deletes the project, and removes the
generated media directory. See `docs/kernels/review-annotation-kernel.md`.

### 5. Color grading

```
resolve_control(action="open_page", params={"page": "color"})
timeline_item_color(action="set_cdl", params={"cdl": {"NodeIndex": 1, "Slope": [1.1, 1.0, 0.9], "Offset": [0.0, 0.0, 0.0], "Power": [1.0, 1.0, 1.0], "Saturation": 1.0}, "track_type": "video", "track_index": 1, "item_index": 0})
timeline_item_color(action="add_version", params={"name": "Grade v2", "track_type": "video", "track_index": 1, "item_index": 0})
timeline_item_color(action="grade_boundary_report", params={"track_type": "video", "track_index": 1, "item_index": 0})
timeline_item_color(action="safe_export_lut", params={"type": "33ptcube", "path": "/tmp/look.cube", "track_type": "video", "track_index": 1, "item_index": 0})
```

For the Color / Grade boundary map, run:

```
python3.11 tests/live_color_grade_validation.py --output-dir /tmp/color-grade-probe
```

The harness creates a disposable project, generates synthetic color-bar media,
probes grade, node graph, version, copy, LUT, Gallery, and color-group
behavior, writes JSON and Markdown reports, deletes the project, and removes
generated media and exported probe files. See `docs/kernels/color-grade-kernel.md`.

### 6. Grab a still and read the grade data

```
resolve_control(action="open_page", params={"page": "color"})
gallery_stills(action="grab_and_export", params={"folder_path": "/tmp/stills", "format": "jpg"})
```

The response includes `files[].data_base64` (the image as base64) and
`files[].data` for the companion `.drx` grade file (plain text XML). The
image reflects the color-graded frame as Resolve sees it, not the raw source.

### 7. Export the timeline

```
timeline(action="export", params={"path": "/tmp/export.edl", "type": "EDL", "subtype": "CMX3600"})
timeline(action="export", params={"path": "/tmp/export.fcpxml", "type": "FCPXML"})
timeline(action="export_timeline_checked", params={"path": "/tmp/export.drt", "format": "drt"})
timeline(action="detect_gaps_overlaps")
timeline(action="conform_boundary_report", params={"handles": 8})
```

For the Timeline Conform / Interchange boundary map, run:

```
python3.11 tests/live_timeline_conform_validation.py --output-dir /tmp/timeline-conform-probe
```

The harness creates a disposable project, generates synthetic media, builds a
gapped timeline, probes structure, source ranges, gap/overlap detection,
interchange export/import/round-trip behavior, synthetic missing-media relink
planning, writes reports, deletes the project, and removes generated media.
See `docs/kernels/timeline-conform-interchange-kernel.md`.

For the Audio / Fairlight boundary map, run:

```
python3.11 tests/live_audio_fairlight_validation.py --output-dir /tmp/audio-fairlight-probe
```

The harness creates a disposable project, generates synthetic video and audio
media, probes track/item audio state, mappings, voice isolation, property
writes, auto-sync, transcription, subtitle generation, Fairlight preset listing,
audio insertion, writes reports, deletes the project, and removes generated
media. See `docs/kernels/audio-fairlight-kernel.md`.

### 8. Add and start a render job

```
render(action="get_formats")
render(action="probe_render_matrix")
render(action="set_format_and_codec", params={"format": "QuickTime", "codec": "H.265 Master"})
render(action="validate_render_settings", params={"settings": {"TargetDir": "/tmp/renders", "CustomName": "review", "SelectAllFrames": true}, "require_temp_target": true})
render(action="prepare_render_job", params={"target_dir": "/tmp/renders", "settings": {"CustomName": "review", "SelectAllFrames": true}})
render(action="add_job")
render(action="list_jobs")
render(action="start")
render(action="is_rendering")
```

For the Render / Deliver boundary map, run:

```
python3.11 tests/live_render_deliver_validation.py --output-dir /tmp/render-deliver-probe
```

The harness creates a disposable project, generates a synthetic timeline, probes
format/codec/resolution compatibility, validates settings, runs a tiny temp
render job, writes reports, deletes the project, and removes generated media and
render outputs.

### 9. Apply a Fusion effect to a timeline item

```
timeline_item_fusion(action="add_comp", params={"track_type": "video", "track_index": 1, "item_index": 0})
fusion_comp(action="add_tool", params={"tool_type": "Glow", "timeline_item": {"track_type": "video", "track_index": 1, "item_index": 0}})
fusion_comp(action="set_input", params={"tool_name": "Glow1", "input_name": "Gain", "value": 0.8, "timeline_item": {"track_type": "video", "track_index": 1, "item_index": 0}})
fusion_comp(action="fusion_boundary_report", params={"timeline_item": {"track_type": "video", "track_index": 1, "item_index": 0}})
```

For the Fusion Composition boundary map, run:

```
python3.11 tests/live_fusion_composition_validation.py --output-dir /tmp/fusion-composition-probe
```

The harness creates a disposable project, generates synthetic video media,
probes timeline item comp creation, safe tool creation, input writes, graph
inspection, connections, bulk writes, frame range, and comp export, writes
reports, deletes the project, and removes generated media. See
`docs/kernels/fusion-composition-kernel.md`.

---

## Error Handling and Recovery

| Error message | Cause | Fix |
|---|---|---|
| `"Not connected to DaVinci Resolve"` | Resolve is not running or scripting is disabled | Call `resolve_control(action="launch")`, wait, retry |
| `"No project open"` | No project is currently loaded | Call `project_manager(action="load", params={"name": "..."})` |
| `"No current timeline"` | Project has no timeline set as current | Call `timeline(action="set_current", params={"index": 1})` |
| `"No item at index N"` | `item_index` out of range for the track | Call `timeline(action="get_items", ...)` first to find valid indices |
| `"Clip not found"` | Stale or wrong `clip_id` | Re-fetch IDs via `media_pool(action="get_selected")` or `folder(action="get_clips")` |
| `"Gallery not available"` | Not on Color page | `resolve_control(action="open_page", params={"page": "color"})` |
| `"GrabStill failed"` | Not on Color page or no clip under playhead | Switch to Color page, move playhead over a clip |
| `"ExportStills failed"` | Gallery panel not open in UI | Instruct user to open Workspace > Gallery |
| `"Tool '...' not found"` | Wrong tool name in Fusion comp | Use `fusion_comp(action="get_tool_list")` to list available tools |
| `"Color group '...' not found"` | Group name mismatch | Use `color_group(action="list")` first |

When a tool returns `{"success": False}` without an error key, the underlying
Resolve API returned `False`. This usually means a precondition was not met
(wrong page, wrong state, context missing). Check the API reference in
`docs/reference/resolve_scripting_api.txt` for the specific method.

---

## Known Gotchas

**Resolve API object lifetimes** — Objects like timelines, clips, and color groups
returned by the API are live references that can become stale if the project state
changes (e.g., the user deletes a timeline). Always re-fetch IDs after any
destructive action.

**`SetName` on the active timeline** — `timeline(action="set_name")` returns
`False` if you try to rename the currently active timeline. Switch to a different
timeline first, rename, then switch back.

**`DeleteProject`** — Returns `False` if the project is currently open. Close it
first.

**CDL value format** — `set_cdl` accepts Slope/Offset/Power as arrays `[R, G, B]`,
tuples, or space-separated strings like `"1.0 1.0 1.0"`. All forms are normalized
internally.

**`GetNodeGraph(0)`** — Passing `0` as `layer_index` to `GetNodeGraph` on a
timeline item returns `False` in Resolve. Use `get_node_graph` without a
`layer_index` to get the default graph.

**Gallery export requires the Gallery panel visible** — `ExportStills` only works
if the Gallery panel is open in the Resolve UI on the Color page. Instruct the
user to open it via Workspace menu if export fails.

**Python version** — Resolve's scripting library works best with Python 3.10–3.12.
Python 3.13+ may cause `scriptapp("Resolve")` to return `None` due to ABI
incompatibilities.

**Resolve version guards** — Resolve 20-specific actions return a clear
`requires DaVinci Resolve 20.x+` error when called against older builds. Resolve
19.1.3 remains the compatibility baseline; Resolve 20 additions were live-tested
on Resolve Studio 20.3.2.

**Source media integrity** — Do not transcode, convert, create proxies, or write
derivatives of source media unless the user explicitly asks. Analysis and tests
should write sidecars or synthetic fixtures, never modify camera originals.

**Windows multi-Python setups** — On Windows with multiple Python installations,
Resolve 20.3 may crash on import unless `PYTHONHOME` is set to the interpreter
used to build the venv. The installer handles this automatically; manual configs
may need it added.

**`item_index` is 0-based** — When specifying `item_index` in params, `0` is the
first item on the track, not `1`.

**`track_index` is 1-based** — Track indices start at `1`, not `0`.

**Fusion comp scope** — `fusion_comp` actions without a timeline scope target the
active composition on the Fusion page. If you intend to operate on a specific
clip's comp, always pass `clip_id`, `timeline_item_id`, or `timeline_item`.

---

## Seeing What Resolve Sees (Visual Context)

The server provides two mechanisms to inspect a frame as Resolve has processed it,
including color grading, effects, and compositing — not just the raw source file.

**`timeline_markers(action="get_thumbnail")`** — Returns raw thumbnail data at
the current playhead position. The response is a dictionary with keys `data`,
`format`, `width`, `height`, `noOfComponents`, and `depth`.

**`timeline_markers(action="get_thumbnail_image")`** — Converts the same current
frame thumbnail to PNG bytes and returns MCP image content without writing a file.

**`gallery_stills(action="grab_and_export", params={...})`** — Grabs a still from
the current frame on the Color page and returns the image encoded as base64 in the
response (`files[].data_base64`). This is the most reliable way to get a
color-graded frame preview as a standard image format (jpg, tif, dpx, etc.)
that can be passed directly to a vision-capable AI model. Requires the Color page
with Gallery panel visible.

To use `grab_and_export` for visual inspection:

```
resolve_control(action="open_page", params={"page": "color"})
gallery_stills(action="grab_and_export", params={
  "folder_path": "/tmp/resolve-preview",
  "format": "jpg",
  "cleanup": true
})
```

The response `files[0].data_base64` is a standard JPEG, base64-encoded. Feed it
to a vision model to describe what Resolve is displaying — including all grading
and effects applied to the source.

---

## Clip ID Reference Pattern

Many tools require a `clip_id` (the UUID of a Media Pool clip) or a timeline item
identified by `track_type + track_index + item_index`. Use this pattern to resolve
both:

```
# List clips in the Media Pool
folder(action="get_clips")
# -> returns [{name, id}, ...]  — use id as clip_id

# List items on a timeline track
timeline(action="get_items", params={"track_type": "video", "index": 1})
# -> returns [{name, id, start, end, duration}, ...]
# Use track_type="video", track_index=1, item_index=<position in this list>
# Or use id to look up later via timeline_item(action="get_unique_id", ...)
```

---

## API Coverage

All 336 non-deprecated methods of the DaVinci Resolve Scripting API are covered.
331 methods have been live-tested across Resolve 19.1.3 Studio and Resolve
20.3.2 Studio. Five methods require infrastructure not available in typical
setups:

| Method | Requires |
|---|---|
| `ProjectManager.CreateCloudProject` | Resolve cloud infrastructure |
| `ProjectManager.LoadCloudProject` | Resolve cloud infrastructure |
| `ProjectManager.ImportCloudProject` | Resolve cloud infrastructure |
| `ProjectManager.RestoreCloudProject` | Resolve cloud infrastructure |
| `Timeline.AnalyzeDolbyVision` | HDR / Dolby Vision content |

The full API reference is in `docs/reference/resolve_scripting_api.txt`.
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
davinci-resolve-mcp

Directory Structure

SKILL.md

Report

Notice
