davinci-resolve-mcp 2.33.0 → 2.33.2

package/docs/authoring/setting-files/references/gotchas.md

@@ -0,0 +1,168 @@
+# Gotchas
+
+Hard-won rules that are not obvious from the stock files. Check against this list whenever an effect "loads but doesn't work."
+
+## 1. `ordered()` vs `{}` — Order Actually Matters
+
+`Inputs = ordered() { ... }` preserves the order you wrote. `Inputs = { ... }` does **not** — Fusion may re-order, which scrambles your inspector layout, breaks `ControlGroup` pairings (consecutive grouping stops working), and shuffles your Page tabs. Always use `ordered()` for:
+
+- `GroupOperator.Inputs`
+- `GroupOperator.Tools` (order determines evaluation order for some purposes)
+- `UserControls`
+
+The internal `Inputs = { ... }` of individual nodes can be unordered — node params are keyed by name.
+
+## 2. `ActiveTool` Must Match a Top-Level Key
+
+`ActiveTool = "MyEffect"` has to name an entry in the outermost `Tools` list. If you rename the GroupOperator without updating `ActiveTool`, the file loads but Resolve doesn't know which node is the "primary" — some categories (titles especially) misbehave.
+
+If there's exactly one top-level node, `ActiveTool` is effectively optional — but set it anyway for clarity.
+
+## 3. `SourceOp` References Must Resolve
+
+Every `SourceOp = "Name"` has to name a node in the *same* `Tools` list. A reference from an `InstanceInput` points into the GroupOperator's internal `Tools`. A reference from inside one internal node's `Input` points to a sibling in that same internal `Tools`. You cannot reach across groups.
+
+Typos here cause silent failures: the effect loads, the control exists, but it doesn't affect anything. When debugging, grep for all `SourceOp = "..."` values and verify each one is defined.
+
+## 4. `Source` Names Are Case-Sensitive and Exact
+
+`XBlurSize` is not the same as `xBlurSize` or `XBlursize`. When you're not sure of the exact parameter name, build the effect in Fusion, save it, and open the `.setting` file — it will contain the authoritative names.
+
+## 5. Transition Progress is Automatic — Don't Look for a "Progress" Parameter
+
+There is no `Progress` or `Time` parameter on the transition GroupOperator. Fusion evaluates internal `LUTLookup` nodes with `Source = FuID { "Duration" }` across the clip duration and produces a 0→1 ramp for free. Use that ramp to drive any animated parameter.
+
+If your transition "plays" in one frame or doesn't animate at all, you probably fed a static value into `Dissolve.Mix` instead of a `LUTLookup`.
+
+## 6. Titles Need `KeyStretcher` or They Don't Stretch
+
+A TextPlus with baked-in `BezierSpline` animation has a fixed length in frames (e.g., the animation runs from frame 1 to frame 120). If you expose its `Output` directly as `MainOutput1`, the title shows its animation in the first 120 frames regardless of clip length — a 5-second title clip will play the animation for the first 4 seconds and freeze for the last 1 second.
+
+Fix: wrap the output in a `KeyStretcher` and output `Source = "Result"`. Set `SourceEnd` to the animation's native length and `StretchStart` / `StretchEnd` to the range you want stretched.
+
+## 7. `MainOutput1.Source` for Titles is `"Result"`, Not `"Output"`
+
+Easy to miss. If your title renders but the animation doesn't stretch properly, check whether you pulled `Output` (unstretched) or `Result` (stretched) from the `KeyStretcher`.
+
+## 8. `Width`, `Height`, `UseFrameFormatSettings` on Generator Nodes
+
+Nodes that generate pixels (`Background`, `FastNoise`, `TextPlus`, `RectangleMask`, `EllipseMask`) have a `Width` / `Height` pair that defines the canvas size. For Edit-page use, always set `UseFrameFormatSettings = Input { Value = 1 }` so the node inherits the timeline's resolution instead of being locked to 1920×1080. Stock effects all do this; skipping it makes your effect break on 4K timelines.
+
+## 9. Namespaced Parameter Keys Need Quoting
+
+Any parameter with a `.` in its name must be wrapped in brackets and quoted:
+
+```lua
+-- wrong
+Gamut.SLogVersion = Input { Value = FuID { "SLog2" } },
+
+-- right
+["Gamut.SLogVersion"] = Input { Value = FuID { "SLog2" } },
+```
+
+This bites hardest on 3D nodes (`Transform3DOp.Translate.X`, `Diffuse.Color.Red`, `SurfaceCylinderInputs.Radius`) and ofx nodes.
+
+## 10. `FuID` Enum Values Must Be Exact
+
+`FuID { "Fast Gaussian" }` is one of several possible enum values for `Blur.Filter`. If you guess the wrong name, the file loads but the parameter falls back to the default and silently ignores you. Don't guess — inspect a working composition or grep the stock files for the node type you're using to find valid values.
+
+## 11. Don't Reuse Internal Node Names Across Groups
+
+Each `GroupOperator` has its own namespace for internal `Tools`. Within a single group, names must be unique. If you want two `Blur` nodes, call them `Blur1` and `Blur2`. Fusion appends `_1`, `_2` when you create duplicates in the UI; in hand-authored files, just number them yourself.
+
+Name collisions produce "last one wins" behavior: only the last definition is honored, and any `SourceOp` references resolve to that last one.
+
+## 12. `Instance_NodeName` is a Magic Pattern
+
+When stock effects need the same internal node available at two points in the graph with slightly different routing, they use the `Instance_` prefix:
+
+```lua
+Rectangle1 = RectangleMask { ... actual params ... },
+
+Instance_Rectangle1 = RectangleMask {
+    SourceOp = "Rectangle1",   -- creates an instance that shares Rectangle1's params
+    Inputs   = { ... different routing ... },
+},
+```
+
+An `Instance_X` with `SourceOp = "X"` at the node level (not inside an `Input`) creates a live clone. Edits to `Rectangle1` propagate to `Instance_Rectangle1`. Use this when you need the same mask / text / curve to appear in two places in the graph.
+
+## 13. `CustomData` is Optional — Strip It
+
+Stock effects carry large `CustomData.Settings` blocks because Fusion saves the full UI state of preset variations into them. You can delete the entire `CustomData = {...}` block from any node you're hand-editing; the effect will still load and work. The blocks just bloat the file and obscure the real logic.
+
+## 14. Restart Resolve Picks Up New Templates
+
+Resolve indexes the Templates folder at launch. Dropping a new `.setting` file in while Resolve is running will NOT make it appear in the Effects Library until you quit and relaunch. (Refreshing via right-click in the library works sometimes, not reliably.)
+
+## 15. A Broken `.setting` Crashes the Category, Not Resolve
+
+If you ship malformed Lua, Resolve skips the file and logs a warning. But a subtler problem — a file that parses but has a dangling `SourceOp` reference or a wrong `Source` name — can make an entire subfolder look empty in the Effects Library. When nothing shows up, move your new file out of the folder temporarily and check whether the rest of the category reappears.
+
+## 16. `Dissolve.Map` is the Wipe Shape
+
+For luma-ramp transitions (`Operation = FuID { "DFTLumaRamp" }`), `Dissolve.Map` takes an image input that defines the shape of the wipe. Bright areas reveal the foreground first, dark areas last. Generate the map with any node: `Background` with a gradient for a linear wipe, `FastNoise` for a dissolve, `RectangleMask` + `Transform` for a box wipe, etc.
+
+## 17. `Fuse.Wireless` is a Carrier, Not a Real Node
+
+`Fuse.Wireless` exists to host `UserControls` entries (buttons, labels, etc.) that don't belong to any real node. It has no pixel output. Don't try to use it in the render graph. Think of it as a "control panel node."
+
+## 18. Files Loose in `Templates/Edit/` Silently Fall Through to the Fusion Library
+
+The Edit-page Effects Library only indexes `.setting` files that live inside a **category subfolder**: `Templates/Edit/Effects/`, `Templates/Edit/Transitions/`, `Templates/Edit/Titles/`, `Templates/Edit/Generators/`. A file dumped directly into `Templates/Edit/` (no category subfolder) is invisible to the Edit page — but the Fusion-page library is laxer and picks it up anyway, so the effect *appears to install successfully*, just in the wrong UI.
+
+Symptom: "I wrote an Edit effect, restarted Resolve, and it's showing up under the Fusion page's Effects Library instead of on the Edit page." Cause: you skipped the `<category>` folder. Always write to the full path including the subfolder:
+
+```
+%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Templates\Edit\Effects\MyBlur.setting
+```
+
+not
+
+```
+%APPDATA%\Blackmagic Design\DaVinci Resolve\Support\Fusion\Templates\Edit\MyBlur.setting
+```
+
+Same rule for Fusion macros: they need a category subfolder too (`Fusion/Tools/`, `Fusion/Backgrounds/`, etc.), not loose in `Fusion/`.
+
+## 19. `.alut3` Files Are LUTs, Not Compositions
+
+`Fusion/Looks/*.alut3` live in the same `Core Davinci Effects` folder structure but they're **plain-text 3D LUTs**, not `.setting` files. Header: `F5LT3\nSize: 33\nType: float32\n\n` followed by R G B triples. They install to the LUT folder and apply from the Color page. Do not try to edit them as Fusion comps.
+
+## 20. `ControlGroup = N` Must Equal the Anchor Input's Number
+
+Fusion collapses controls into one inspector row when they share a `ControlGroup` integer. That integer must equal the `InputN` number of the preceding label/anchor Input in the list — not a free-choice group ID. In `CCTV.setting`, `Font` (Input2) and `Style` (Input3) both carry `ControlGroup = 2` because they share a row anchored to `Input2`. In `Background Reveal Lower Third.setting`, `VerticalJustificationTop`, `VerticalJustificationCenter`, and `VerticalJustificationBottom` (Input7/8/9) all carry `ControlGroup = 6`, grouping them under the `Input6` row anchor. If you pick sequential integers starting from 1, grouping silently breaks: controls render on separate rows and multi-button radios disappear.
+
+Rule: count from the top of your `Inputs = ordered() { ... }` block and use the anchor row's `InputN` number as the group ID for all siblings that share that row.
+
+## 21. `Width` on `InstanceInput` Is Inspector Column Width, Not Mask Size
+
+`Width` means two completely different things depending on context. On mask nodes (`EllipseMask`, `RectangleMask`) it is the physical mask size as a fraction of image width — e.g., `Ellipse1.Width = 0.5069` in `Binoculars.setting` is the mask diameter, not a UI hint. On an `InstanceInput`, `Width` is a fractional inspector column width (0.0–1.0): `DSLR.setting` exposes five timecode fields each with `Width = 0.5`, packing them two-per-row in the inspector. `Width = 1` (the default when omitted) gives the control its own full row.
+
+A related field, `ICD_Width`, serves the same purpose inside `UserControls` button definitions. Authors packing button grids who accidentally copy a mask-scale value like `0.5069` produce weirdly-wide or full-row controls.
+
+## 22. `GlobalOut` on Internal Generator Nodes — Set It, Keep It Consistent
+
+`GlobalOut` on a generator or text node caps its internal frame timeline. Every `TextPlus`, `Background`, and `FastNoise` inside an effect with baked animation must carry `GlobalOut = Input { Value = N }`, and all nodes in the same group must share the same `N`. In `CCTV.setting`, every generator node carries `GlobalOut = 716`. If you omit `GlobalOut`, the node's internal timeline is unbounded and Resolve may render garbage or refuse to stretch the effect to clip length. If siblings in the same group have different `GlobalOut` values, animation phases drift out of sync.
+
+## 23. Fusion Bare-Node Comps Don't Work as Edit Effects — Edit Requires `GroupOperator`
+
+All `Edit/Effects/`, `Edit/Transitions/`, `Edit/Titles/`, and `Edit/Generators/` stock files wrap their graph in a `GroupOperator` with `InstanceInput`s. Several Fusion categories — especially `Fusion/Styled Text/` — ship raw top-level node trees with no `GroupOperator` and no exposed `InstanceInput`s at all. In those cases, users customize by opening the node graph on the Fusion page. On the Edit page this model fails silently: the effect loads, appears in the Effects Library, but has a blank inspector.
+
+If you copy `Fusion/Styled Text/Alien.setting` (bare nodes, no GroupOperator) as a starting point for a new Edit effect, you get an unusable empty-inspector result. Always wrap Edit-page effects in a `GroupOperator`. `Edit/Effects/Binoculars.setting` is a clean example of the required structure.
+
+## 24. Transition Easing Uses `LUTLookup` + `LUTBezier`, Not `BezierSpline`
+
+For parameters that need to follow transition progress (0→1 over clip duration), the stock pattern is a `LUTLookup` node with its `Lookup` input connected to a sibling `LUTBezier`. `LUTBezier` uses `KeyColorSplines` with an outer `[0]` (single channel index) and inner float keys 0.0–1.0 (normalized position). This is completely different from `BezierSpline`, which uses `KeyFrames` with absolute frame numbers. Hand-authored effects that drive transition progress via a `BezierSpline` with frame keys play at wrong timing or freeze.
+
+A bare `LUTLookup {}` with no `Lookup` input (as in `Cross Dissolve.setting`) automatically consumes the built-in `Duration` source for a default linear 0→1 ramp — leaving `Lookup` disconnected is valid shorthand for "linear progress." `Box Wipe.setting` shows the full explicit form with a custom `LUTBezier` easing curve.
+
+## 25. `BTNCS_Execute` Lua References `InputN` Keys, Not Internal Node Parameter Names
+
+`Fuse.Wireless` buttons use `BTNCS_Execute` to call `tool:SetInput(...)`. The first argument must be the exposed `InstanceInput` key name (e.g., `'Input9'`), not the underlying node's parameter name (e.g., `'Start'`). In `Box Wipe.setting`, direction-preset buttons call `tool:SetInput('Input9', {x,y})` to write the wipe start position — `Input9` is the `InstanceInput` key that wraps `Background2.Start`. Writing `tool:SetInput('Start', ...)` silently does nothing because `Start` isn't a top-level `GroupOperator` input. Authors naturally reach for the internal param name since that's what they see in the node graph.
+
+## 26. OFX Nodes Require a Mandatory Boilerplate Input Block
+
+Every `ofx.com.blackmagicdesign.resolvefx.*` node in the stock files carries seven required OFX overlay parameters: `blendGroup`, `blendIn`, `blend`, `ignoreContentShape`, `legacyIsProcessRGBOnly`, `refreshTrigger`, and `resolvefxVersion`. Both `Binoculars.setting` and `Digital Glitch.setting` include this block on every OFX node. Omitting any one of these causes the node to fall back to defaults that may differ from your intent, or the effect fails to load entirely. `resolvefxVersion` should match the version the effect was authored against (e.g., `"2.2"`); mismatches can cause parameter layout changes in newer Resolve versions.
+
+Authors hand-writing OFX invocations rather than copying from a stock file invariably omit this block. Copy the seven-field block verbatim from any working stock OFX node.

package/docs/authoring/setting-files/references/thumbnails.md

@@ -0,0 +1,106 @@
+# Thumbnail Files
+
+Each `.setting` (or `.alut3`) ships with a bundle of PNGs named after the effect file. They are not embedded — they live as sibling files in the same folder. Resolve indexes them at launch and uses them for the tiles in the Effects Library. If your effect is `My Cool Thing.setting`, every thumbnail starts with `My Cool Thing.` followed by a suffix that identifies the UI slot. Spaces in the base name are fine — Resolve matches on exact prefix.
+
+---
+
+## Suffix Catalog
+
+Every distinct suffix found in the stock library, with confirmed dimensions and purpose.
+
+| Suffix | Dimensions (1×) | Dimensions (`@2x`) | UI slot |
+|--------|-----------------|---------------------|---------|
+| `.large.png` | 128 × 128 | 256 × 256 | Square tile in grid/icon view |
+| `.large@2x.png` | — | 256 × 256 | HiDPI version of `.large.png` |
+| `.small.png` | 30 × 30 | 60 × 60 | Small icon in list/compact view |
+| `.small@2x.png` | — | 60 × 60 | HiDPI version of `.small.png` |
+| `.small.active.png` | 30 × 30 | 60 × 60 | Button pressed/active state |
+| `.small.active@2x.png` | — | 60 × 60 | HiDPI active state |
+| `.small.hover.png` | 30 × 30 | 60 × 60 | Mouse-hover state |
+| `.small.hover@2x.png` | — | 60 × 60 | HiDPI hover state |
+| `.small.push.png` | 30 × 30 | 60 × 60 | Mouse-down state |
+| `.small.push@2x.png` | — | 60 × 60 | HiDPI push state |
+| `.wide.png` | 52 × 29 | 104 × 58 | Wide tile (transitions, titles) |
+| `.wide@2x.png` | — | 104 × 58 | HiDPI wide tile |
+| `.wide.active.png` | 52 × 29 | 52 × 29 | Active state for wide tile |
+| `.wide.active@2x.png` | — | 104 × 58 | HiDPI wide active state |
+| `.wide.hover.png` | 52 × 29 | 52 × 29 | Hover state for wide tile |
+| `.wide.hover@2x.png` | — | 104 × 58 | HiDPI wide hover state |
+| `.wide.push.png` | 52 × 29 | 52 × 29 | Push state for wide tile |
+| `.wide.push@2x.png` | — | 104 × 58 | HiDPI wide push state |
+
+The full 12-suffix set (`.large`, `.large@2x`, `.small`, `.small@2x`, `.small.active`, `.small.active@2x`, `.small.hover`, `.small.hover@2x`, `.small.push`, `.small.push@2x`, `.wide`, `.wide@2x`) is the standard complement for most categories. Categories that omit `.large.*` use only the wide/small subsets.
+
+---
+
+## Per-Category Reference
+
+All 14 stock categories verified against the `Core Davinci Effects/` library (2,897 PNG files total).
+
+**Suffix set key:**
+- **Full-12** = `.large`, `.large@2x`, `.small`, `.small@2x`, `.small.active`, `.small.active@2x`, `.small.hover`, `.small.hover@2x`, `.small.push`, `.small.push@2x`, `.wide`, `.wide@2x`
+- **Wide-only** = `.wide`, `.wide@2x` (no large or small variants)
+- **Partial** = some effects have the full set, some have a smaller subset — see notes
+
+| # | Category | Baseline thumbnail set | Notes |
+|---|----------|----------------------|-------|
+| 1 | **Edit / Effects** | Full-12 | 22 of 23 effects ship the full-12. Both `_default.png` and `_default.wide.png` fallbacks present. |
+| 2 | **Edit / Transitions** | Partial | 30 of 53 effects ship full-12 including `.large.*`. All 53 have `.wide` + `.wide@2x`. Most have `.small.*` button states. `.wide.active@2x`, `.wide.hover@2x`, `.wide.push@2x` exist but only on a single effect. |
+| 3 | **Edit / Titles** | Partial | Baseline is wide-only (`.wide`, `.wide@2x`) across 90 of 97 titles. 18 titles additionally ship the full-12 (`.large.*` + `.small.*` button states). Do not assume titles are always wide-only. |
+| 4 | **Edit / Generators** | Partial | Baseline is full-12. 14 of 16 effects have `.large.*`. All have `.wide.*`. Not all have `.small.*` button states. |
+| 5 | **Fusion / Tools** | Full-12 | All Tools effects ship the complete 12-suffix set. |
+| 6 | **Fusion / Backgrounds** | Full-12 | All Backgrounds effects ship the complete 12-suffix set. |
+| 7 | **Fusion / Generators** | Full-12 | All Fusion Generators ship the complete 12-suffix set. |
+| 8 | **Fusion / Particles** | Partial | Some effects ship full-12; some ship only `.large.*` + `.wide.*` without `.small.*` button states. |
+| 9 | **Fusion / Shaders** | Full-12 | All Shaders ship the complete 12-suffix set. |
+| 10 | **Fusion / Motion Graphics** | Full-12 | All Motion Graphics ship the complete 12-suffix set. |
+| 11 | **Fusion / Lens Flares** | Full-12 | All Lens Flares ship the complete 12-suffix set. |
+| 12 | **Fusion / Looks** | Mixed | Only `.setting`-based effects get thumbnails; `.alut3` files do not get per-file thumbnails. The one `.setting` effect (`Posterize`) ships the full-12. The 10 `.alut3` files (e.g. `Abstract.alut3`, `Film chrome.alut3`) carry no per-effect thumbnail — only `_default.png` and `_default@2x.png` serve as fallbacks for the whole category. |
+| 13 | **Fusion / Styled Text** | Wide-only | All Styled Text effects use only `.wide` + `.wide@2x`. No `.large.*` or `.small.*` variants. |
+| 14 | **Fusion / How To** | None (defaults only) | Zero per-effect thumbnails in this category. All 12 How To `.setting` files share only the two `_default` fallbacks (`_default.png`, `_default@2x.png`). Do not try to add `.large.png` thumbnails here — the UI does not render them for How To entries. |
+
+**Minimum viable ship:**
+- For any category that uses `.large.*`: provide at least `.large.png` (128×128). Resolve handles the rest with fallbacks.
+- For titles and transitions: provide at least `.wide.png` (52×29).
+- For Styled Text: provide `.wide.png` + `.wide@2x.png`.
+- For Looks `.alut3` files: no per-effect thumbnail is possible; the category relies entirely on `_default.*`.
+
+---
+
+## `_default.*` Fallbacks
+
+Every stock Edit and Fusion folder ships a small set of fallback files that Resolve displays when no per-effect thumbnail exists.
+
+| File | Dimensions | Role |
+|------|-----------|------|
+| `_default.png` | 52 × 29 | Fallback for the wide slot. Despite the name suggesting a "default large", this file is actually wide-sized — do not use it as a large-thumbnail fallback. |
+| `_default@2x.png` | 256 × 256 | HiDPI fallback; note the dimension mismatch — `_default.png` is wide-sized (52×29) while `_default@2x.png` is large-sized (256×256). The two files are not matched scales. |
+| `_default.wide.png` | 52 × 29 | Explicit wide-slot fallback, present in Edit category folders alongside `_default.png`. |
+| `_default.wide@2x.png` | 104 × 58 | HiDPI version of the wide-slot fallback. |
+
+The `_default.wide.*` pair is distinct from `_default.*` — both exist side-by-side in Edit folders. When building new categories, supply your own `_default.png` and `_default@2x.png` rather than relying on Resolve's built-in fallback graphic.
+
+---
+
+## Creating Thumbnails
+
+1. Apply the effect to a clip in Resolve.
+2. Grab a frame (File → Export → Still, or viewer right-click → Grab Still).
+3. Crop to the target dimensions with any image tool. Alpha PNGs are supported.
+4. Name the crops per the suffix rules above and drop next to the `.setting` file.
+
+For button states (`.active`, `.hover`, `.push`), start from the base `.small.png` and brighten / darken / tint by ~10% — this matches the stock library's approach.
+
+---
+
+## Quirks — Stock Anomalies (Do Not Replicate)
+
+These are bugs or accidents in the stock library. They are documented here so authors recognize them as anomalies, not as valid naming patterns.
+
+- **Double-dot typo:** `Stretch Region.small.@2x.png` and `Watermark.small.@2x.png` in `Edit/Effects/` have an extra dot (`.small.@2x.png` instead of `.small@2x.png`). Resolve ignores these files; the correct form is `.small@2x.png` with no dot before `@2x`.
+
+- **Bare-suffix transition:** `Rotate 90.png` and `Rotate 90@2x.png` in `Edit/Transitions/` have no slot suffix at all — just the base name with `.png`. This appears to be a naming error; use an explicit slot suffix on every thumbnail.
+
+- **Compound Slide name:** The transition `Slide.push` has its base name parsed as `Slide.push`, producing filenames like `Slide.push.small.push.png` and `Slide.push.small.push@2x.png`. This is a side effect of the base name containing a dot. Avoid dots in effect base names.
+
+None of these patterns are understood by Resolve as intentional slots — authors should not replicate them.

package/install.py

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

package/package.json

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

package/src/granular/common.py

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

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.33.0"
+VERSION = "2.33.2"
 
 import base64
 import os
@@ -1173,6 +1173,18 @@ def _requires_method(obj, method_name, min_version):
         return None
     return _err(f"{method_name} requires DaVinci Resolve {min_version}+")
 
+def _is_truncated(text):
+    """True if a transcription preview was cut off.
+
+    Resolve's `Transcription` clip property is a preview that ends with an
+    ellipsis (… or ...) when the full transcript is longer than the property
+    exposes, so the caller knows the returned text is partial.
+    """
+    if not isinstance(text, str):
+        return False
+    t = text.rstrip()
+    return t.endswith("…") or t.endswith("...")
+
 _MARKER_COLORS = [
     "Blue", "Cyan", "Green", "Yellow", "Red", "Pink", "Purple", "Fuchsia",
     "Rose", "Lavender", "Sky", "Mint", "Lemon", "Sand", "Cocoa", "Cream",
@@ -5408,6 +5420,22 @@ def _audio_mapping_report(mp, tl, p: Dict[str, Any]):
     return {"timeline_items": timeline_items, "media_pool_items": clip_rows}
 
 
+def _clip_name(clip):
+    try:
+        return clip.GetName()
+    except Exception:
+        return None
+
+
+def _synced_audio(clip):
+    """Best-effort read of whether a clip currently has synced audio linked."""
+    try:
+        v = clip.GetClipProperty("Synced Audio")
+    except Exception:
+        return False
+    return bool(v) and str(v).strip() not in ("", "None", "0", "Off", "No")
+
+
 def _safe_auto_sync_audio(mp, p: Dict[str, Any]):
     root = mp.GetRootFolder()
     resolved, err = _clips_from_params(root, mp, p)
@@ -5421,7 +5449,26 @@ def _safe_auto_sync_audio(mp, p: Dict[str, Any]):
     settings = _normalize_auto_sync_settings(dict(p.get("settings") or {}), get_resolve())
     if p.get("dry_run", True):
         return _ok(would_auto_sync=True, clips=_clip_summaries(clips), missing=missing, settings=settings)
-    return {"success": bool(mp.AutoSyncAudio(clips, settings)), "count": len(clips), "missing": missing, "settings": settings}
+    # Read-back verification: AutoSyncAudio's boolean return is unreliable, so
+    # capture each clip's "Synced Audio" linkage before and after and report the
+    # delta. Trust `linked`/`newly_linked`, not `success`.
+    before = [_synced_audio(c) for c in clips]
+    ok = bool(mp.AutoSyncAudio(clips, settings))
+    linked, newly_linked, already_linked = [], [], []
+    for c, was in zip(clips, before):
+        name = _clip_name(c)
+        if _synced_audio(c):
+            linked.append(name)
+            (already_linked if was else newly_linked).append(name)
+    return {
+        "success": ok,
+        "linked": linked,
+        "newly_linked": newly_linked,
+        "already_linked": already_linked,
+        "count": len(clips),
+        "missing": missing,
+        "settings": settings,
+    }
 
 
 def _resolve_audio_constant(resolve_obj, name: str, fallback):
@@ -13626,6 +13673,9 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       get_unique_id(clip_id) -> {id}
       transcribe_audio(clip_id, use_speaker_detection?) -> {success}  — use_speaker_detection is Resolve 21+
       clear_transcription(clip_id) -> {success}
+      get_transcription(clip_id) -> {text, truncated, status, has_transcription}
+        Read a clip's transcription. `truncated` flags when Resolve's preview
+        property cut the text off (the full transcript is longer).
       perform_audio_classification(clip_id) -> {success}  — Resolve 21+
       clear_audio_classification(clip_id) -> {success}  — Resolve 21+
       analyze_for_intellisearch(clip_id, identify_faces?, is_better_mode?) -> {success}  — Resolve 21+, AI IntelliSearch Extra
@@ -13827,6 +13877,20 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         return {"success": bool(clip.TranscribeAudio(bool(usd)))}
     elif action == "clear_transcription":
         return {"success": bool(clip.ClearTranscription())}
+    elif action == "get_transcription":
+        raw = clip.GetClipProperty("Transcription")
+        text = raw if isinstance(raw, str) else ("" if raw is None else str(raw))
+        try:
+            status = clip.GetClipProperty("Transcription Status")
+        except Exception:
+            status = None
+        return {
+            "clip_id": p.get("clip_id"),
+            "text": text,
+            "truncated": _is_truncated(text),
+            "status": status or None,
+            "has_transcription": bool(text.strip()),
+        }
     elif action == "perform_audio_classification":
         missing = _requires_method(clip, "PerformAudioClassification", "21.0")
         if missing:
@@ -13905,7 +13969,7 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         return {"success": bool(clip.SetMarkInOut(p["mark_in"], p["mark_out"], p.get("type", "all")))}
     elif action == "clear_mark_in_out":
         return {"success": bool(clip.ClearMarkInOut(p.get("type", "all")))}
-    return _unknown(action, ["get_name","get_metadata","set_metadata","get_third_party_metadata","set_third_party_metadata","get_media_id","get_clip_property","set_clip_property","get_clip_color","set_clip_color","clear_clip_color","link_proxy","unlink_proxy","replace_clip","set_name","link_full_resolution_media","monitor_growing_file","replace_clip_preserve_sub_clip","get_unique_id","transcribe_audio","clear_transcription","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur","get_audio_mapping","get_mark_in_out","set_mark_in_out","clear_mark_in_out","open_in_viewer"])
+    return _unknown(action, ["get_name","get_metadata","set_metadata","get_third_party_metadata","set_third_party_metadata","get_media_id","get_clip_property","set_clip_property","get_clip_color","set_clip_color","clear_clip_color","link_proxy","unlink_proxy","replace_clip","set_name","link_full_resolution_media","monitor_growing_file","replace_clip_preserve_sub_clip","get_unique_id","transcribe_audio","clear_transcription","get_transcription","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur","get_audio_mapping","get_mark_in_out","set_mark_in_out","clear_mark_in_out","open_in_viewer"])
 
 
 # ═══════════════════════════════════════════════════════════════════════════════