davinci-resolve-mcp 2.23.0

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -0,0 +1,99 @@
+# Timeline Conform / Interchange Kernel
+
+The Timeline Conform / Interchange kernel expands `timeline` into a safer
+structure, source-range, gap/overlap, interchange, comparison, missing-media,
+and relink-planning layer.
+
+Live validation was run against DaVinci Resolve Studio 20.3.2.9 with a
+disposable `_mcp_timeline_conform_probe_*` project and generated synthetic
+video/audio media. Final release probe counts:
+
+| Status | Count |
+| --- | ---: |
+| `supported` | 17 |
+| `partially_supported` | 1 |
+| `unsupported` | 0 |
+| `version_or_page_dependent` | 0 |
+| `not_applicable` | 0 |
+| `error` | 0 |
+
+The partially supported result was FCPXML round-trip survival: export and import
+both worked, but the imported timeline did not preserve MediaPoolItem-name
+linkage in the comparison snapshot. DRT round-trip matched exactly.
+
+## Added Actions
+
+All actions are exposed through `timeline`.
+
+| Action | Purpose |
+| --- | --- |
+| `conform_capabilities` | Return structure, analysis, interchange, relink-planning, and source-media safety boundaries. |
+| `probe_timeline_structure` | Snapshot timeline identity, track counts, items, source ranges, media file paths, markers, and optional clip properties. |
+| `detect_gaps_overlaps` | Report same-track gaps and overlaps from the current timeline snapshot. |
+| `source_range_report` | Group source frame ranges by MediaPoolItem/file path, with optional handles and merging. |
+| `export_timeline_checked` | Resolve export aliases and guard timeline export paths to temp locations by default. |
+| `import_timeline_checked` | Guard timeline imports from temp locations and normalize import options. |
+| `compare_timelines` | Compare current timeline to another timeline or two supplied snapshots. |
+| `probe_interchange_roundtrip` | Export, import, compare, and optionally delete the imported timeline. |
+| `detect_missing_media` | Detect missing/offline media using Resolve status fields and file-path existence. |
+| `build_relink_plan` | Read-only search-root scan for relink candidates by missing file basename. |
+| `conform_boundary_report` | Return capabilities, timeline structure, gaps/overlaps, source ranges, and missing-media summary. |
+
+## Interchange Matrix
+
+| Format Alias | Export | Round Trip | Notes |
+| --- | --- | --- | --- |
+| `drt` | Supported | Supported | DRT export/import compared with zero differences in the live probe. |
+| `fcpxml` | Supported | Partially supported | Resolve exported a folder containing `Info.fcpxml`; import worked after resolving the primary file, but MediaPoolItem-name linkage was not preserved. |
+| `edl` | Supported | Not forced in release probe | Export succeeded to temp path. EDL round trips can be lossy by design. |
+| `aaf` | Supported | Not forced in release probe | Export succeeded to temp path. AAF options and media relink behavior are build/content dependent. |
+| `otio` | Supported | Not forced in release probe | Export succeeded to temp path. |
+
+Supported aliases include `aaf`, `drt`, `edl`, `edl_cdl`, `edl_sdl`,
+`edl_missing_clips`, `fcp7xml`, `fcpxml`, `fcpxml_1_8`, `fcpxml_1_9`,
+`fcpxml_1_10`, and `otio`.
+
+## Supported Findings
+
+- Timeline structure snapshots worked across video, audio, and subtitle track
+  categories.
+- Same-track gap detection found the deliberate 24-frame video gap in the
+  generated timeline.
+- Source range reporting grouped generated media paths with requested handles.
+- Guarded exports succeeded for FCPXML, DRT, EDL, AAF, and OTIO.
+- FCPXML directory-style exports are normalized with a `primary_file` path.
+- DRT export/import/compare round-trip succeeded and cleaned up the imported
+  timeline.
+- Synthetic-only unlink, missing-media detection, relink candidate planning,
+  and safe relink all worked through generated media.
+
+## Boundaries
+
+- Interchange formats are not semantically equivalent. DRT is the strongest
+  project-native round-trip path; EDL and FCPXML can lose Resolve-specific
+  relationships.
+- The public API exposes timeline items, source ranges, markers, and some media
+  references, but not full transition/effect/retime semantics for every format.
+- `build_relink_plan` is intentionally read-only. Execute relinks through
+  `media_pool.safe_relink` only with synthetic or explicitly approved paths.
+- Missing-media status fields vary by Resolve build. The kernel combines status
+  text with local file existence when a file path is available.
+- Export and import helpers require temp paths by default because they write
+  interchange artifacts.
+
+## Live Probe
+
+Run the live boundary probe with:
+
+```bash
+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 JSON and Markdown reports, deletes the project, and removes
+generated media.
+
+Use `--keep-open` only when you intentionally want to inspect the disposable
+project by hand.

package/docs/kernels/timeline-edit-kernel.md

@@ -0,0 +1,189 @@
+# Timeline Edit Kernel Boundary
+
+The timeline edit kernel is the supported MCP layer for clip duplication,
+range-copy workflows, and timeline-item state copying. It is built only on
+DaVinci Resolve's public scripting API and preserves source media integrity:
+it references existing Media Pool items and never transcodes, renders, proxies,
+or creates derivatives of source media.
+
+## Live Probe Summary
+
+The current boundary was validated on DaVinci Resolve Studio 20.3.2.9 with
+disposable projects and generated synthetic media.
+
+Final exhaustive probe result from May 9, 2026:
+
+| Status | Count |
+| --- | ---: |
+| Supported | 255 |
+| Partially supported | 4 |
+| Unsupported | 138 |
+| Version/page dependent | 4 |
+| Errors | 0 |
+
+The probe first runs the live duplicate/range validation harness, then creates
+a separate disposable project to inspect runtime method availability, timeline
+operations, item properties, keyframes, metadata, cache/voice/take/Fusion/grade
+surfaces, and known API boundaries.
+
+Run it with:
+
+```bash
+python3.11 tests/live_duplicate_clips_validation.py --output-dir /tmp/timeline-kernel-probe
+```
+
+The output directory receives both JSON and Markdown reports. Reports are
+generated artifacts and should not be committed.
+
+## Supported Kernel Features
+
+### Clip duplication
+
+`timeline(action="duplicate_clips")` duplicates existing video timeline items
+by re-appending the same Media Pool item with the same source trim through
+`MediaPool.AppendToTimeline([{clipInfo}])`.
+
+Supported placement modes:
+
+- `same_time`
+- `offset`
+- `at_playhead`
+- `track_above`
+- `after_source`
+- `next_gap`
+
+Supported placement controls:
+
+- `clip_ids` from timeline item unique IDs
+- `selected=True` when Resolve exposes selected/current item state
+- `target_track_index`
+- `track_offset`
+- `record_frame`
+- `record_frame_offset`
+
+`copy_clips` is an alias for duplication. `move_clips` duplicates successfully
+first, then deletes the original source items.
+
+### Linked audio
+
+`include_linked=True` duplicates linked audio items alongside the source video
+item when Resolve exposes linked item handles. The kernel restores the
+video/audio link state on the duplicated items.
+
+### Range operations
+
+The range tools build exact append operations from overlapping source segments:
+
+- `copy_range`
+- `duplicate_range`
+- `overwrite_range`
+- `lift_range`
+
+`copy_range` and `duplicate_range` copy exact video/audio source segments from
+explicit `start_frame`/`end_frame` values or the current mark in/out. The
+destination uses `record_frame` and optional track targeting.
+
+`overwrite_range` deletes whole destination items that overlap the destination
+range, then appends the copied range.
+
+`lift_range` deletes whole timeline items in a range. Partial overlaps are
+blocked by default because Resolve does not expose a public razor/split
+primitive. Passing `allow_partial_item_delete=True` confirms deletion of whole
+overlapping items; it does not perform a partial trim.
+
+### Copyable item state
+
+The kernel can copy these state groups when Resolve exposes readable/writable
+item APIs for the current item type and page state:
+
+- `transform`
+- `crop`
+- `composite`
+- `audio`
+- `retime`
+- `dynamic_zoom`
+- `scaling`
+- `stabilization`
+- `clip_color`
+- `markers`
+- `flags`
+- `enabled`
+- `cache`
+- `voice_isolation`
+- `fusion`
+- `grades`
+- `takes`
+- `keyframes`
+
+`copy_properties=True` copies all supported groups. A list or comma-separated
+string can scope copying to specific groups. `copy_keyframes=True` adds the
+`keyframes` group.
+
+### Capability reporting
+
+`timeline(action="edit_kernel_capabilities")` returns the maintained support
+map for supported, partially supported, and unsupported behavior.
+
+`timeline(action="probe_edit_kernel_item")` is a read-only item probe. It
+reports method availability, `GetProperty()` output, known property values,
+keyframe counts, and linked item summaries.
+
+`timeline(action="title_property_scan")` inspects undocumented title and
+generator `TimelineItem.GetProperty()` keys for the selected item scope.
+`set_title_text` and `bulk_set_title_text` use explicit or scanned keys when a
+Resolve build accepts `SetProperty()` writes for title text payloads.
+
+## Partial Support
+
+The probe classifies a feature as partially supported when Resolve exposes a
+public API surface, but success can vary by item type, page, build, or current
+UI state.
+
+Current partial areas:
+
+- Audio properties: some timeline audio `SetProperty` calls return false on
+  Resolve Studio 20.3.2.9.
+- Dynamic zoom, scaling, and stabilization: copied through exposed
+  `TimelineItem.GetProperty`/`SetProperty` keys when the build accepts writes.
+- Edit-page title and generator text: `title_property_scan` can expose
+  undocumented Text+ keys, but key names and write acceptance vary by item type,
+  page, and Resolve build.
+- Cache and voice isolation: copied only when item-level read/write APIs are
+  callable for the item.
+- Keyframes: copied for exposed properties, but Resolve does not expose enough
+  interpolation detail for full-fidelity readback in every case.
+
+## Unsupported Boundaries
+
+These are blocked by Resolve's public scripting API, not by MCP plumbing:
+
+- Transition cloning: no public timeline-item transition clone/read/write API.
+- Razor/split edits: no direct public timeline split primitive.
+- True partial lift: no safe partial-item delete without a split primitive.
+- Source-less item cloning through append: titles, generators, Fusion
+  compositions, and subtitles can exist on the timeline, but source-less items
+  do not provide a Media Pool item that `AppendToTimeline([{clipInfo}])` can
+  clone.
+- Deep speed-ramp semantics: exposed retime properties and supported keyframes
+  can be copied, but opaque speed-ramp curves are not independently inspectable.
+
+## Version/Page Dependent Behavior
+
+Some behavior depends on Resolve's current page or bridge state:
+
+- `selected=True` can fail to resolve selected/current timeline items when
+  Resolve does not expose selection state to the scripting bridge.
+- After inserting or probing source-less items, some Resolve bridge states lose
+  a callable `Project.SetCurrentTimeline`; the probe reports this as
+  version/page dependent rather than a kernel failure.
+- `probe_edit_kernel_item` is stable when the project has a current timeline;
+  if Resolve loses current timeline state, the harness records the bridge
+  condition separately.
+
+## Development Guardrails
+
+- Use disposable projects and synthetic media for live validation.
+- Never write to, transcode, render, proxy, or create derivatives of source
+  media while testing timeline-kernel behavior.
+- Treat generated probe reports as local artifacts.
+- Add new API experiments to the live probe when expanding the boundary map.

package/docs/notes/codec-plugin-notes.md

@@ -0,0 +1,136 @@
+# DaVinci Resolve Codec Plugin Notes
+
+Blackmagic's CodecPlugin README documents the DaVinci Resolve IO Encode Plugin
+SDK. These plugins extend Resolve Studio's Deliver page with additional render
+containers/codecs. They are native encode plugins, not a Python scripting API
+surface.
+
+The SDK is encode-focused: it enables additional codecs and container formats
+that can be rendered directly from Resolve. It does not describe a decoder or
+Media Pool import plugin API. Blackmagic notes that only CPU-based plugins are
+currently supported.
+
+## Current MCP Surface
+
+The MCP cannot build, install, load, or configure codec plugins directly.
+Relevant existing render actions are:
+
+- `render(action="get_formats")` wraps `Project.GetRenderFormats()`.
+- `render(action="get_codecs", params={"format": "..."})` wraps
+  `Project.GetRenderCodecs(renderFormat)`.
+- `render(action="set_format_and_codec", params={"format": "...", "codec": "..."})`
+  wraps `Project.SetCurrentRenderFormatAndCodec(format, codec)`.
+- `render(action="get_format_and_codec")` wraps
+  `Project.GetCurrentRenderFormatAndCodec()`.
+- `render(action="get_resolutions", params={"format": "...", "codec": "..."})`
+  wraps `Project.GetRenderResolutions(format, codec)`.
+- `render(action="set_settings")`, `render(action="add_job")`, and
+  `render(action="start")` run the normal render pipeline once Resolve exposes
+  the desired format/codec.
+
+After an IO encode plugin is installed and Resolve is restarted, plugin-provided
+formats and codecs should appear through the same format/codec query actions.
+There is no documented Resolve scripting method to list codec plugin bundles or
+distinguish built-in codecs from plugin-provided codecs.
+
+## Plugin Packaging
+
+Codec plugins are native binaries:
+
+| Platform | Binary type |
+|---|---|
+| macOS | 64-bit dynamic library |
+| Linux | 64-bit shared object |
+| Windows | 64-bit DLL |
+
+Plugins are packaged as `.dvcp.bundle` folders:
+
+```text
+PLUGIN.dvcp.bundle
+  Contents/
+    ARCH_1/
+      PLUGIN.dvcp
+    ARCH_2/
+      PLUGIN.dvcp
+```
+
+The plugin name must match in both the bundle name and binary name.
+
+Supported architecture folder names:
+
+| Platform | Architecture folder |
+|---|---|
+| macOS | `MacOS` for Universal2 or Arm64 |
+| macOS Intel | `MacOS-x86-64`, checked before `MacOS` on Intel-only machines |
+| Linux | `Linux-x86-64` |
+| Windows | `Win64` |
+
+## Install Locations
+
+Install the `.dvcp.bundle` into Resolve's `IOPlugins` folder:
+
+| Platform | IOPlugins folder |
+|---|---|
+| macOS | `/Library/Application Support/Blackmagic Design/DaVinci Resolve/IOPlugins` |
+| macOS App Store | `~/Library/Containers/com.blackmagic-design.DaVinciResolveAppStore/Data/Library/Application Support/IOPlugins` |
+| Linux | `/opt/resolve/IOPlugins` |
+| Windows | `%ProgramData%\Blackmagic Design\DaVinci Resolve\Support\IOPlugins` |
+
+System-wide install paths may require administrator privileges. Installing or
+replacing native codec plugins should remain an explicit user request.
+
+## Sample Plugin
+
+The developer package includes `Examples/x264_encoder_plugin`, which wraps the
+x264 encoder. The sample flow is:
+
+1. Build/install x264 from source.
+2. Point `.mk.defs` on macOS/Linux or `plugin2015.vcxproj` on Windows at the
+   x264 install path.
+3. Build with `make` on macOS/Linux or Visual Studio on Windows.
+4. Package the resulting binary into a `.dvcp.bundle` architecture folder.
+5. Copy the bundle to `IOPlugins`.
+6. Restart Resolve.
+
+Once loaded, the plugin's supported containers should appear in the Deliver page
+format list. If a plugin-supported container, or QuickTime, is selected, the
+plugin's codecs should appear in the codec list and expose any plugin-specific
+render-settings UI.
+
+## Practical Failure Checks
+
+If a custom codec is missing from `render.get_formats` or `render.get_codecs`:
+
+- Confirm Resolve Studio supports the plugin and has been restarted after
+  installation.
+- Confirm the bundle suffix is `.dvcp.bundle`.
+- Confirm the bundle and binary names match exactly.
+- Confirm the architecture folder matches the current platform and CPU.
+- Confirm the plugin binary is in `Contents/<ARCH>/PLUGIN.dvcp`.
+- Confirm the plugin is an encode plugin for Deliver, not an import/decode
+  extension.
+- Confirm any external codec library dependencies, such as x264, can be found by
+  the plugin at runtime.
+- Query formats first, then codecs for the selected format. A codec may only
+  appear for specific containers.
+
+## Useful Future Additions
+
+Good repo additions, if codec-plugin troubleshooting becomes common:
+
+1. A read-only IOPlugins inventory helper that scans known plugin folders and
+   reports `.dvcp.bundle` structure, architecture folders, and matching binary
+   names.
+2. Better `render.set_format_and_codec` failure text that suggests checking
+   `render.get_formats`, `render.get_codecs`, plugin install paths, and restart
+   requirements.
+3. A developer checklist for packaging `.dvcp.bundle` outputs from the bundled
+   x264 sample.
+4. No automatic native build/install flow by default. Codec plugins are native
+   executable code in system/plugin directories and should stay opt-in.
+
+## Source Media Integrity
+
+Codec plugins affect render output from Resolve. They should not be used as a
+reason to transcode, proxy, or replace source media unless the user explicitly
+asks for that derivative workflow.

package/docs/notes/dctl-notes.md

@@ -0,0 +1,234 @@
+# DaVinci Resolve DCTL Notes
+
+Blackmagic's DaVinciCTL README documents DaVinci Color Transform Language
+(DCTL). DCTLs are GPU-accelerated, C-like pixel programs used by Resolve as
+programmable color transforms, ResolveFX DCTL effects, DCTL transitions, and
+custom ACES IDT/ODT transforms.
+
+This is adjacent to, but not the same as, the Python scripting API used by the
+MCP. The MCP can refresh Resolve's LUT list and set discovered LUT-style files
+on Color page nodes, but it does not compile DCTL, encrypt DCTL, or manipulate
+ResolveFX DCTL plugin UI controls directly.
+
+## Current MCP Surface
+
+Relevant existing actions:
+
+- `project_settings(action="refresh_luts")` wraps `Project.RefreshLUTList()`.
+  Call it after adding or editing `.dctl`, `.dctle`, or `.cube` files in
+  Resolve's LUT folders.
+- `graph(action="set_lut", params={"node_index": 1, "lut_path": "..."})`
+  wraps `Graph.SetLUT(nodeIndex, lutPath)`. DCTLs that Resolve exposes through
+  LUT selection follow the same discovery constraints as LUTs.
+- `graph(action="get_lut", params={"node_index": 1})` wraps `Graph.GetLUT()`.
+- `graph(action="get_tools_in_node", ...)` may report ResolveFX tools present
+  in a Color page node, but the scripting API does not expose a general
+  "configure DCTL plugin parameter" helper.
+
+There is no documented Resolve scripting method to list installed DCTLs, encrypt
+DCTLs, choose a DCTL in the ResolveFX DCTL plugin, or apply a DCTL transition.
+
+## DCTL Types
+
+Blackmagic describes two primary DCTL types:
+
+- Transform DCTL: processes a single clip/frame. It can be applied as a LUT, via
+  the ResolveFX DCTL plugin, from the LUT browser, or from clip/node LUT
+  selection.
+- Transition DCTL: blends two clips over time and is used through the OpenFX
+  DCTL Transition plugin under ResolveFX Color.
+
+DCTL source files are plain text `.dctl` files. Resolve can encrypt a DCTL from
+the LUT browser, producing an expiring `.dctle` file for distribution.
+
+## Transform Entry Points
+
+Every transform DCTL must provide exactly one supported `transform()` entry
+point. Common signatures are:
+
+```c
+__DEVICE__ float3 transform(int p_Width, int p_Height, int p_X, int p_Y, float p_R, float p_G, float p_B)
+__DEVICE__ float3 transform(int p_Width, int p_Height, int p_X, int p_Y, __TEXTURE__ p_TexR, __TEXTURE__ p_TexG, __TEXTURE__ p_TexB)
+```
+
+Resolve 19.1 added transform DCTL with alpha for the ResolveFX DCTL plugin:
+
+```c
+__DEVICE__ float4 transform(int p_Width, int p_Height, int p_X, int p_Y, float p_R, float p_G, float p_B, float p_A)
+__DEVICE__ float4 transform(int p_Width, int p_Height, int p_X, int p_Y, __TEXTURE__ p_TexR, __TEXTURE__ p_TexG, __TEXTURE__ p_TexB, __TEXTURE__ p_TexA)
+```
+
+Alpha mode tags:
+
+```c
+DEFINE_DCTL_ALPHA_MODE_STRAIGHT
+DEFINE_DCTL_ALPHA_MODE_PREMULTIPLY
+```
+
+If no alpha tag is specified for an alpha transform, Resolve defaults to
+premultiplied alpha.
+
+## Transition Entry Point
+
+Transition DCTLs use a `transition()` function and read the global
+`TRANSITION_PROGRESS` value, which runs from `0.0f` to `1.0f` over the
+transition:
+
+```c
+__DEVICE__ float4 transition(
+    int p_Width,
+    int p_Height,
+    int p_X,
+    int p_Y,
+    __TEXTURE__ p_FromTexR,
+    __TEXTURE__ p_FromTexG,
+    __TEXTURE__ p_FromTexB,
+    __TEXTURE__ p_FromTexA,
+    __TEXTURE__ p_ToTexR,
+    __TEXTURE__ p_ToTexG,
+    __TEXTURE__ p_ToTexB,
+    __TEXTURE__ p_ToTexA)
+```
+
+Texture signatures can sample pixels with `_tex2D(texture, x, y)`.
+
+## Language Notes
+
+DCTL is C-like and uses base C types plus Resolve-specific qualifiers and vector
+types:
+
+- `float2`, `float3`, `float4`
+- `make_float2`, `make_float3`, `make_float4`
+- `__TEXTURE__`
+- `__DEVICE__`
+- `__CONSTANT__`
+- `__CONSTANTREF__`
+
+Float literals need an `f` suffix, for example `1.2f`.
+
+Useful global keys:
+
+- `__RESOLVE_VER_MAJOR__` and `__RESOLVE_VER_MINOR__` for version guards.
+- `DEVICE_IS_CUDA`, `DEVICE_IS_OPENCL`, and `DEVICE_IS_METAL` for backend guards.
+- `TRANSITION_PROGRESS` in transition DCTLs.
+- `TIMELINE_FRAME_INDEX` when running through the ResolveFX DCTL plugin.
+  When a DCTL is used as a LUT, this defaults to `1`.
+
+Headers can be included relative to the `.dctl` file:
+
+```c
+#include "ColorConversion.h"
+```
+
+## LUTs Inside DCTL
+
+DCTL can reference external `.cube` LUTs:
+
+```c
+DEFINE_LUT(FilmToVideo, ../LUT/Blackmagic Design/Blackmagic_46K_Film_to_Video.cube)
+```
+
+It can also define inline cube LUTs with `DEFINE_CUBE_LUT(...) { ... }`
+starting in Resolve 17. Use `APPLY_LUT(r, g, b, lutName)` to apply either kind.
+
+Rules:
+
+- Define LUTs before use.
+- Multiple LUTs may be defined and applied in one DCTL.
+- External LUTs must be `.cube` files.
+- 1D and shaper LUTs use linear interpolation.
+- 3D LUTs use the project's 3D LUT interpolation setting: trilinear or
+  tetrahedral.
+
+See `docs/notes/lut-notes.md` for the cube file format itself.
+
+## Custom UI
+
+Transform DCTLs used through the ResolveFX DCTL plugin can define UI controls
+with `DEFINE_UI_PARAMS`. Resolve supports:
+
+- `DCTLUI_SLIDER_FLOAT`
+- `DCTLUI_SLIDER_INT`
+- `DCTLUI_VALUE_BOX`
+- `DCTLUI_CHECK_BOX`
+- `DCTLUI_COMBO_BOX`
+- `DCTLUI_COLOR_PICKER`
+
+Each type can have up to 64 controls per DCTL. Resolve 19.1 added the color
+picker, tooltips, incremental slider steps, and improved build-error handling.
+
+Tooltips use:
+
+```c
+DEFINE_UI_TOOLTIP(Target Color, "Choose target color")
+```
+
+Build errors from the ResolveFX DCTL plugin appear in Resolve's DCTL Build Error
+dialog. After editing a DCTL file, the plugin combo-box Reset rebuilds the
+selected DCTL while preserving custom UI values when possible.
+
+## DCTL And ACES
+
+Custom ACES DCTLs live outside the normal LUT folder and are loaded at Resolve
+startup from:
+
+| Platform | ACES transform root |
+|---|---|
+| macOS | `~/Library/Application Support/Blackmagic Design/DaVinci Resolve/ACES Transforms` |
+| Windows | `%AppData%\Blackmagic Design\DaVinci Resolve\Support\ACES Transforms` |
+| Linux | `~/.local/share/DaVinciResolve/ACES Transforms` |
+| iPadOS | `On My iPad/DaVinciResolve/ACES Transforms` |
+
+Use `IDT/` for Input Device Transforms and `ODT/` for Output Device Transforms.
+Resolve discovers these at startup, not through `RefreshLUTList()`.
+
+ACES DCTL modes:
+
+- Non-parametric ACES transforms with
+  `DEFINE_ACES_PARAM(IS_PARAMETRIC_ACES_TRANSFORM: 0)`.
+- Parametric ACES Transform V1 with `DEFINE_ACES_PARAM(...)`, supported for
+  ACES 1.1 through 1.3.
+- Parametric ACES Transform V2 with `DEFINE_ACES_V2_PARAM(...)`, supported by
+  Resolve 20.1 for ACES 2.0.
+
+V1 supports custom EOTF functions and skipping the standard ACES RRT. V2 uses
+the newer `DEFINE_ACES_V2_PARAM` template and adds Gamma 2.2, but does not
+support custom EOTF or skipping RRT.
+
+## Practical Failure Checks
+
+If a DCTL does not appear or does not apply:
+
+- Confirm the file is in Resolve's LUT directory for normal DCTL/plugin use, or
+  in the user ACES `IDT/` or `ODT/` folder for ACES transforms.
+- Call `project_settings(action="refresh_luts")` after adding/editing normal
+  DCTL files; restart Resolve for ACES DCTLs.
+- Confirm the file extension is `.dctl` or `.dctle`.
+- Confirm the exact entry point signature and parameter names match the required
+  form.
+- Confirm float constants use the `f` suffix where needed.
+- Confirm external headers and `DEFINE_LUT` paths are relative to the DCTL file
+  or absolute.
+- For transform-with-alpha behavior, confirm Resolve is 19.1+ and the alpha
+  mode tag matches the intended straight/premultiplied workflow.
+- For animated/noise effects, remember `TIMELINE_FRAME_INDEX` is meaningful in
+  the DCTL plugin but defaults to `1` when used as a LUT.
+
+## Useful Future Additions
+
+Good repo additions, if DCTL workflows become common:
+
+1. A read-only DCTL inventory helper that scans Resolve LUT roots and ACES
+   transform roots.
+2. A lightweight DCTL linter for entry point signatures, UI param count, include
+   paths, `DEFINE_LUT` paths, and obvious missing `f` suffixes.
+3. Better `graph.set_lut` failure text that mentions `.dctl` discovery,
+   `RefreshLUTList()`, and DCTL-vs-ResolveFX-plugin limitations.
+4. A small fixture set using Blackmagic's simple examples (`Gain.dctl`,
+   `GainDCTLPlugin.dctl`, `LUTApply.dctl`) for non-rendering parser tests.
+
+## Source Media Integrity
+
+DCTLs process pixels in Resolve's grade/effects pipeline. Do not bake DCTL
+results into camera originals, create transformed copies, or export/reimport
+processed media unless the user explicitly asks for that workflow.