davinci-resolve-mcp 2.23.0

package/docs/notes/fusion-template-notes.md

@@ -0,0 +1,136 @@
+# DaVinci Resolve Fusion Template Notes
+
+Blackmagic's Fusion Templates README documents `.setting` templates used by the
+Edit and Cut page Effects Library. This is relevant to the MCP because several
+timeline actions insert named Fusion generators and titles, and failures often
+come down to template location, category, naming, or Resolve needing a restart.
+
+## Current MCP Surface
+
+The scripting API overlap is useful but narrow:
+
+- `timeline(action="insert_fusion_generator", params={"name": "..."})` wraps
+  `Timeline.InsertFusionGeneratorIntoTimeline(generatorName)`.
+- `timeline(action="insert_fusion_title", params={"name": "..."})` wraps
+  `Timeline.InsertFusionTitleIntoTimeline(titleName)`.
+- `timeline(action="insert_fusion_composition")` inserts an empty Fusion
+  composition into the current timeline.
+- `timeline_item_fusion` manages Fusion comps already attached to timeline
+  items, including import/export of Fusion compositions.
+- `fusion_comp` edits the node graph of the active Fusion comp or a scoped
+  timeline-item comp.
+
+Fusion template `.setting` files are not the same thing as exported Fusion comp
+files used by `timeline_item_fusion.import_comp`. Treat template installation
+and Fusion-comp import as different workflows.
+
+## Template Categories
+
+Fusion templates are macro or group `.setting` files saved into category folders:
+
+| Category | Shape |
+|---|---|
+| Transitions | Two image inputs and one output. |
+| Generators | No image inputs and one output. |
+| Titles | Generator-style templates centered on Text+ or Text3D. |
+| Effects | One image input and one output, applied to clips from the Effects tab. |
+
+The MCP currently has direct timeline insertion helpers for Fusion generators
+and Fusion titles. The Resolve scripting API does not expose a general
+"install Fusion template" or "list Fusion templates" method.
+
+## Template Paths
+
+Fusion templates live under `Fusion/Templates/` in platform-specific roots:
+
+| Platform | All users | Specific user |
+|---|---|---|
+| macOS | `/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Templates/` | `/Users/<UserName>/Library/Application Support/Blackmagic Design/DaVinci Resolve/Fusion/Templates/` |
+| Windows | `C:\ProgramData\Blackmagic Design\DaVinci Resolve\Fusion\Templates\` | `C:\Users\<UserName>\AppData\Roaming\Blackmagic Design\DaVinci Resolve\Support\Fusion\Templates\` |
+| Linux | `/var/BlackmagicDesign/DaVinci Resolve/Fusion/Templates/` or `/home/resolve/Fusion/Templates/` | `$HOME/.local/share/DaVinciResolve/Fusion/Templates/` |
+
+Only templates under this Edit-page hierarchy show up on the Cut and Edit pages:
+
+```text
+Edit/
+  Transitions/
+  Titles/
+  Generators/
+  Effects/
+```
+
+Templates saved elsewhere may still be visible from the Fusion page Effects
+Library but not from the Edit/Cut page categories used by timeline insertion.
+
+## Animation Guidance
+
+Fusion template animation should generally use the Anim Curves modifier instead
+of fixed-time keyframes. Edit/Cut page template duration is driven by the edit
+length or transition curve, so fixed-time keyframes will not adapt cleanly when
+an editor changes duration.
+
+Anim Curves timing sources:
+
+- `Duration` times animation to the edit duration.
+- `Transition` follows duration and also uses the Edit page transition curve.
+- `Custom` reveals an input that can be driven manually by another spline or
+  modifier.
+
+Anim Curves supports linear, easing, and custom curves, plus mirror, invert,
+scale, offset, clipping, time scale, and time offset controls.
+
+## Assets, Icons, And DRFX Bundles
+
+Since Resolve 17.2, Fusion templates can include bundled assets such as images,
+FBX models/cameras, and LUTs. Inside templates, the `Setting:` path map points
+to the directory containing the loaded `.setting` file. Examples:
+
+```text
+Setting:leaf.jpg
+Setting:Models/object.fbx
+```
+
+Resolve also supports a `.png` icon next to a `.setting` file when both share
+the same base name. Blackmagic recommends `104 x 58`; very large icons may slow
+Resolve startup.
+
+`.drfx` bundles are ordinary zip files renamed with a lower-case `.drfx`
+extension. They can contain multiple templates, icons, and assets. For Edit/Cut
+recognition, keep the same `Edit/Titles`, `Edit/Generators`,
+`Edit/Transitions`, and `Edit/Effects` folder hierarchy inside the bundle.
+
+## Practical Failure Checks
+
+If `insert_fusion_generator` or `insert_fusion_title` fails:
+
+- Confirm the template is in the matching `Edit/Generators` or `Edit/Titles`
+  folder.
+- Restart Resolve after adding template files.
+- Confirm the display/template name matches the string passed to the API.
+- Check whether the template category is wrong; transitions and effects are not
+  inserted by the generator/title helpers.
+- Check any `Setting:` assets are present beside the `.setting` file or in the
+  expected subfolder.
+- For animated templates, inspect whether fixed keyframes were used where Anim
+  Curves were needed.
+
+## Useful Future Additions
+
+Good repo additions, if Fusion template workflows become common:
+
+1. A read-only Fusion template inventory helper that scans known template roots
+   and reports `.setting` files by category.
+2. Better failure text for `insert_fusion_generator` and `insert_fusion_title`
+   that points users to category folders, restart requirements, and name checks.
+3. A small example that installs a user-local generator/title template and then
+   inserts it with the existing timeline actions. Keep system-wide install
+   paths explicit because they may require administrator privileges.
+4. A DRFX inspection helper that verifies lower-case `.drfx`, zip structure,
+   category folders, icons, and referenced `Setting:` assets.
+
+## Source Media Integrity
+
+Fusion templates and bundled assets affect Resolve's timeline/render pipeline.
+They should not modify camera originals. Do not bake template effects into
+source media, create rendered derivatives, or export/reimport processed media
+unless the user explicitly asks for that workflow.

package/docs/notes/lut-notes.md

@@ -0,0 +1,136 @@
+# DaVinci Resolve LUT Notes
+
+Blackmagic's LUT developer README documents Resolve's supported `.cube` LUT
+format. This is directly relevant to the MCP's color tools because Resolve will
+only apply LUTs that it can parse and discover.
+
+## Current MCP Surface
+
+The scripting API already exposes the important LUT operations:
+
+- `project_settings(action="refresh_luts")` wraps `Project.RefreshLUTList()`.
+  Call this after adding LUT files to Resolve's LUT folders.
+- `graph(action="set_lut", params={"node_index": 1, "lut_path": "..."})`
+  wraps `Graph.SetLUT(nodeIndex, lutPath)`.
+- `graph(action="get_lut", params={"node_index": 1})` wraps
+  `Graph.GetLUT(nodeIndex)`.
+- `timeline_item_color(action="export_lut", ...)` wraps
+  `TimelineItem.ExportLUT(exportType, path)`.
+- `graph(action="apply_arri_cdl_lut")` wraps `Graph.ApplyArriCdlLut()`.
+- `project_manager(action="export_project", params={"with_stills_and_luts": true})`
+  can include LUTs in a `.drp` export.
+
+`SetLUT()` uses 1-based node indexes and succeeds only for LUT paths Resolve has
+already discovered. The `lut_path` may be absolute or relative to Resolve's
+master/custom LUT paths.
+
+## Cube LUT Format
+
+A `.cube` file is a text file with a header followed by lookup-table data.
+Resolve supports:
+
+- 1D LUTs
+- 3D LUTs
+- An optional 1D shaper LUT before a 1D or 3D LUT
+
+### 1D LUT
+
+Header keywords:
+
+```text
+LUT_1D_SIZE N
+LUT_1D_INPUT_RANGE MIN_VAL MAX_VAL
+```
+
+`N` is the number of entries, up to 65536. Each data row contains three
+space-separated floating point values for output R, G, and B. Rows map evenly
+from `MIN_VAL` to `MAX_VAL`; values between rows are linearly interpolated.
+
+### 3D LUT
+
+Header keywords:
+
+```text
+LUT_3D_SIZE N
+LUT_3D_INPUT_RANGE MIN_VAL MAX_VAL
+```
+
+`N` is the number of samples per channel, so the file must contain `N * N * N`
+data rows. Each row contains output R, G, and B. Resolve expects the R axis to
+change fastest, then G, then B. Resolve supports trilinear and tetrahedral
+interpolation for 3D LUTs.
+
+### Shaper LUT
+
+A shaper LUT is a 1D LUT placed before the main LUT. It remaps the input range
+so the main 1D/3D LUT can spend more samples on important parts of the signal,
+for example a log curve's lower code values.
+
+## Optional Properties
+
+Comments begin with `#` and are ignored by the parser.
+
+The optional title form is:
+
+```text
+TITLE "Description"
+```
+
+Resolve applies LUTs in data range, with values normalized from `0.0` to `1.0`.
+For LUTs designed around video range values, the cube file can declare:
+
+```text
+LUT_IN_VIDEO_RANGE
+LUT_OUT_VIDEO_RANGE
+```
+
+Those flags tell Resolve to compensate when applying the LUT inside its
+data-range processing pipeline.
+
+## Built-In LUT Locations
+
+Blackmagic's examples live in the installed LUT folder:
+
+| Platform | LUT folder |
+|---|---|
+| macOS | `/Library/Application Support/Blackmagic Design/DaVinci Resolve/LUT` |
+| Linux | `/opt/resolve/LUT` |
+| Windows | `%PROGRAMDATA%\Blackmagic Design\DaVinci Resolve\LUT` |
+
+Example built-in LUT categories include `VFX IO`, `Blackmagic Design`, and
+`ACES`.
+
+## Practical Failure Checks
+
+If `graph.set_lut` fails or `graph.get_lut` returns empty:
+
+- Confirm the current page/context has a valid Color graph and the node index is
+  1-based.
+- Confirm the LUT file is in a Resolve LUT folder or is referenced by a valid
+  absolute path.
+- Call `project_settings(action="refresh_luts")` after adding or changing LUT
+  files.
+- Check the `.cube` header and row count. 3D LUTs must contain exactly
+  `N * N * N` rows.
+- Confirm the file extension is `.cube` and the content is plain text.
+- Check whether video-range flags are needed; wrong range assumptions can look
+  like a broken grade even when the file parses.
+
+## Useful Future Additions
+
+Good repo additions, if LUT troubleshooting becomes common:
+
+1. A read-only `.cube` validator that checks header shape, row count, numeric
+   values, shaper/main LUT ordering, and video-range flags.
+2. A read-only LUT folder inventory helper that scans known Resolve LUT roots.
+   This would be a filesystem diagnostic, not a Resolve API list.
+3. Better `graph.set_lut` failure text that reminds users to refresh the LUT
+   list and verify the 1-based node index.
+4. A tiny synthetic LUT fixture for tests of any future validator.
+
+## Source Media Integrity
+
+Applying a LUT in Resolve changes the grade/render pipeline, not the source
+media file on disk. Do not bake LUTs into camera originals, create transformed
+copies, or export/reimport derivative media unless the user explicitly asks for
+that workflow.

package/docs/notes/openfx-notes.md

@@ -0,0 +1,120 @@
+# DaVinci Resolve OpenFX Notes
+
+Blackmagic's OpenFX developer package is for building native C++ image-effect
+plugins that Resolve can load. It is not a separate control API for this MCP
+server. The MCP can call Resolve scripting methods that reference installed OFX
+generators, but it should not try to compile, install, or manage OFX bundles
+unless the user explicitly asks.
+
+## What The Bundled Package Contains
+
+The installed Resolve developer package includes:
+
+| Directory | Purpose |
+|---|---|
+| `OpenFX-1.4` | Official OpenFX header files. |
+| `Support` | C++ wrapper/support library around the OFX C plugin API. |
+| `GainPlugin` | Single-input filter sample with CPU, CUDA, OpenCL, and Metal render paths. |
+| `TemporalBlurPlugin` | Temporal sample that requests neighboring frames. |
+| `DissolveTransitionPlugin` | Transition sample with two compulsory inputs and a `Transition` parameter. |
+| `RandomFrameAccessPlugin` | Sample that demonstrates random temporal frame access. |
+
+Each sample includes Xcode project files, Visual Studio files, and a Makefile.
+The plugin source is split between the plugin class/factory files and optional
+GPU kernel files:
+
+- `[PluginName].h`
+- `[PluginName].cpp`
+- `CudaKernel.cu`
+- `OpenCLKernel.cpp`
+- `MetalKernel.mm`
+
+## Plugin Install Locations
+
+Compiled plugins produce a `[PluginName].ofx.bundle` directory. Resolve discovers
+plugins from the standard OFX plugin folders:
+
+| Platform | OFX plugin folder |
+|---|---|
+| macOS | `/Library/OFX/Plugins` |
+| Linux | `/usr/OFX/Plugins` |
+| Windows | `C:\Program Files\Common Files\OFX\Plugins` |
+
+Installing into these locations is outside normal MCP behavior because it writes
+to system plugin directories and may require administrator privileges.
+
+## OFX Plugin Shape
+
+The bundled samples follow the OpenFX support-library pattern:
+
+- Subclass `OFX::ImageProcessor` and implement processing paths such as
+  `processImagesCUDA`, `processImagesOpenCL`, `processImagesMetal`, and
+  `multiThreadProcessImages`.
+- Subclass `OFX::ImageEffect`; `render()` is the core render callback.
+- Implement `isIdentity()` when a parameter state can pass the source through
+  unchanged.
+- Implement `changedParam()` and `changedClip()` for host notifications.
+- Implement `getFramesNeeded()` for temporal effects that need neighboring or
+  random frames.
+- Keep `setupAndProcess()` as the handoff from Resolve render arguments to the
+  image processor.
+- Implement a factory with `describe()`, `describeInContext()`, and
+  `createInstance()`.
+- Register factories through `OFX::Plugin::getPluginIDs()`.
+
+Important Resolve/OpenFX capability flags from the samples:
+
+- `OFX::eContextFilter` is for a traditional one-input effect.
+- `OFX::eContextTransition` requires two input clips plus the standard
+  transition parameter.
+- `setNoSpatialAwareness(true)` tells the host the result does not depend on
+  neighboring pixels, which can make an effect eligible during LUT generation.
+- `setTemporalClipAccess(true)` is needed for effects that request frames beyond
+  the current source frame.
+- `setSupportsCudaRender`, `setSupportsOpenCLRender`, and
+  `setSupportsMetalRender` advertise GPU render paths to the host.
+- If using the host-provided CUDA stream, call `setSupportsCudaStream(true)`.
+  If using an internal/default stream, synchronize GPU work before returning
+  from `render()`.
+
+## What This Means For The MCP
+
+The current scripting overlap is small and already present:
+
+- `timeline(action="insert_ofx_generator", params={"name": "..."})` wraps
+  `Timeline.InsertOFXGeneratorIntoTimeline(generatorName)`.
+- `graph(action="get_tools_in_node", ...)` can report OFX tools present in a
+  color node when Resolve exposes them.
+
+The Resolve scripting README does not expose a general "list installed OFX
+plugins" method. If an OFX insert fails, the likely causes are:
+
+- The named OFX generator is not installed in Resolve's OFX plugin path.
+- Resolve has not been restarted since the bundle was installed.
+- The plugin is an effect/transition rather than an OFX generator accepted by
+  `InsertOFXGeneratorIntoTimeline`.
+- The plugin name/grouping shown in Resolve does not match the string passed to
+  the scripting API.
+- The plugin failed to load because of host capability, binary compatibility, or
+  GPU/backend issues.
+
+## Useful Future Additions
+
+Good repo additions, if this becomes a real workflow need:
+
+1. A read-only diagnostic helper that scans standard OFX plugin folders and
+   reports discovered `.ofx.bundle` names. This would be a filesystem inventory,
+   not a Resolve API guarantee.
+2. Better error text for `insert_ofx_generator` that points users to plugin
+   install paths and restart/name-mismatch checks.
+3. A small developer example showing how an installed OFX generator can be
+   inserted through the MCP, plus how to inspect resulting Color-page node tools.
+4. No automatic OFX install/build flow by default. Compiling and installing
+   native plugins is a system-level operation and should stay explicit.
+
+## Source Media Integrity
+
+OpenFX effects process frames provided by Resolve and should not modify camera
+originals. Any generated renders, caches, logs, or diagnostics should remain
+explicit outputs, cache files, or sidecars. Do not use OFX examples as a reason
+to create proxies or derivatives of source media without a direct user request.

package/docs/process/release-process.md

@@ -0,0 +1,152 @@
+# Release Process
+
+This checklist is the required path for version bumps, tags, and GitHub
+Releases. It exists so fixes do not ship without the matching release artifact,
+and so Resolve behavior changes are live-tested before release.
+
+## Version Selection
+
+Use semantic versioning:
+
+- Patch (`x.y.Z`) for bug fixes, docs, test harnesses, and release-process
+  hardening that do not add public tool surface.
+- Minor (`x.Y.0`) for new MCP actions, new documented parameters, new tools, or
+  workflow capabilities.
+- Major (`X.0.0`) for breaking behavior, renamed tools/actions, or removed
+  public API surface without a compatible replacement.
+
+When in doubt, choose the smallest version bump that accurately describes the
+public API impact.
+
+## Files To Update
+
+Every release bump must update all version surfaces:
+
+- `src/server.py`
+- `src/granular/common.py`
+- `install.py`
+- `package.json`
+- README version badge
+- README current stats or latest-release summary when they changed
+- `CHANGELOG.md` latest release entry
+- `docs/SKILL.md` when tool discovery, examples, or behavior changed
+- Git tag, e.g. `v2.4.1`
+- GitHub Release notes
+
+Do not consider a release complete until the GitHub Release exists and is marked
+latest when appropriate.
+
+## Required Validation
+
+Always run static checks before release:
+
+```bash
+venv/bin/python tests/test_import.py
+venv/bin/python scripts/audit_api_parity.py
+node bin/davinci-resolve-mcp.mjs --help
+node bin/davinci-resolve-mcp.mjs --version
+npm pack --dry-run
+git diff --check
+```
+
+Run focused unit tests for the changed surface. For recent timeline/marker
+helpers, this usually includes:
+
+```bash
+venv/bin/python -m unittest tests.test_extract_source_frame_ranges tests.test_marker_params tests.test_v232_helpers tests.test_v233_helpers tests.test_append_clip_infos_result_handling
+```
+
+Behavior changes that touch DaVinci Resolve scripting must also have a live
+Resolve validation before release. Use disposable projects and synthetic media
+only. Never modify, transcode, proxy, or create derivatives of source media
+unless the user explicitly requests it.
+
+Examples:
+
+```bash
+env RESOLVE_SCRIPT_API="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting" \
+  RESOLVE_SCRIPT_LIB="/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so" \
+  PYTHONPATH="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting/Modules" \
+  python3.11 tests/live_marker_validation.py
+
+env RESOLVE_SCRIPT_API="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting" \
+  RESOLVE_SCRIPT_LIB="/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Libraries/Fusion/fusionscript.so" \
+  PYTHONPATH="/Library/Application Support/Blackmagic Design/DaVinci Resolve/Developer/Scripting/Modules" \
+  venv/bin/python tests/live_v233_validation.py
+```
+
+One-off live harnesses are acceptable during review, but reusable coverage
+should live under `tests/`. Do not commit generated media or disposable project
+artifacts.
+
+Docs-only releases do not require a Resolve live run, but the release notes
+should say that no behavior changed.
+
+## Release Checklist
+
+1. Start from a clean tracked worktree. Leave unrelated untracked user files
+   alone.
+2. Merge or land the feature/fix commit.
+3. Update all version surfaces, README current stats, and `CHANGELOG.md`.
+4. Run required static checks, focused unit tests, and live Resolve validation
+   when behavior changed.
+5. Commit the release bump with a conventional commit, for example:
+
+   ```bash
+   git commit -m "chore(release): bump version to 2.4.1"
+   ```
+
+6. Push `main`.
+7. Create and push the annotated tag:
+
+   ```bash
+   git tag -a v2.4.1 -m "v2.4.1"
+   git push origin v2.4.1
+   ```
+
+8. Create the GitHub Release:
+
+   ```bash
+   gh release create v2.4.1 \
+     --repo samuelgursky/davinci-resolve-mcp \
+     --title "v2.4.1" \
+     --notes-file /path/to/release-notes.md \
+     --latest
+   ```
+
+9. Verify the result:
+
+   The `Publish npm package` workflow publishes the npm package from `v*` tags.
+   The npm package should use trusted publishing/OIDC and provenance, not a
+   long-lived npm token.
+
+   ```bash
+   gh release list --repo samuelgursky/davinci-resolve-mcp --limit 5
+   git tag --list "v2.4.*" --sort=-v:refname
+   ```
+
+## Release Notes Template
+
+```markdown
+## vX.Y.Z
+
+Short release summary.
+
+### Added
+
+- ...
+
+### Fixed
+
+- ...
+
+### Documentation
+
+- ...
+
+### Validation
+
+- Unit/static checks run.
+- Live Resolve validation details, or "No Resolve behavior changed; live test
+  not required."
+```