davinci-resolve-mcp 2.81.0 → 2.82.1

package/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.82.1
+
+Corrects the Resolve version the v2.82.0 subtitle-style validation was actually
+run against.
+
+### Fixed
+
+- **v2.82.0 claimed the subtitle-style write path was confirmed on Resolve 21.
+  It was confirmed on Resolve Studio 19.1.3.** The validation itself stands —
+  Resolve opened the patched track and re-serialised it to its own zstd form
+  with the patched values intact — but it was run against 19.1.3, which is the
+  build that was installed. Corrected in `api_truth`, the codec header, and the
+  changelog. If anything this widens the supported range rather than narrowing
+  it, but the version on the claim has to be the one actually tested.
+- **`GetFairlightPresets` / `ApplyFairlightPresetToCurrentTimeline` require
+  Resolve 20.2.2+**, now recorded in the `api_truth` Fairlight entry. On 19.1.3
+  both are absent (confirmed live), so on older builds the per-parameter gap
+  really is the whole story and the preset workaround is unavailable.
+
+## What's New in v2.82.0
+
+Caption styling, which the scripting API cannot touch at all, is now readable
+and writable — plus a correction to a claim this repo was about to send to
+Blackmagic.
+
+### Added
+
+- **`project_db list_subtitle_styles` / `set_subtitle_style`** — read and patch
+  the caption style on a subtitle track: font family, point size, weight,
+  italic, and normalised on-screen position. The scripting API exposes none of
+  this (subtitle `TimelineItem`s return only the 21 transform/composite
+  properties, and every `subtitleFontName`/`subtitlePreset`-shaped setting key
+  returns `None`), but the style is persisted in `Sm2TiTrack.FieldsBlob` for
+  `Type = 2` tracks: a keyed-dict holding an `EffectFiltersBA` payload whose
+  effect 136 carries a Qt `QFont::toString()` descriptor (param 18) and a
+  position vector (param 17). New codec at
+  `resolve-advanced/vendor/drp-format/subtitle-style.js`.
+
+  Verified live on Resolve Studio 19.1.3 (2026-08-06): a patched track opens without error
+  and, once Resolve next re-serialises it, is written back out in Resolve's own
+  zstd form with the patched values intact — so Resolve genuinely parses the
+  write rather than passing the bytes through. Read side verified against a
+  real project carrying 12 subtitle tracks.
+
+  Caveats, all reported by the tool: this is a whole-**track** style and not
+  per-caption, the project must be CLOSED, Resolve must be fully quit and
+  relaunched afterwards, and the track must already carry a style blob — a
+  freshly added subtitle track has none until it is styled once in the UI.
+
+  Only the font descriptor and position are named. The neighbouring parameters
+  vary across real projects but have not been correlated against the UI, so
+  they round-trip untouched and are reported as opaque rather than guessed at.
+
+### Fixed
+
+- **The `api_truth` Fairlight entry claimed more was missing than actually is.**
+  It read "only voice-isolation state and channel-mapping reads are scriptable",
+  which omits `Project.ApplyFairlightPresetToCurrentTimeline(name)` — already
+  exposed as `project_settings apply_fairlight_preset`, with the names coming
+  from `resolve_control get_fairlight_presets`. The real gap is *per-parameter*
+  control (volume/pan/EQ/automation/FairlightFX), not the whole surface. Since
+  this text generates `docs/reference/api-limitations.md`, the incorrect claim
+  was headed for the Blackmagic submission. The subtitle-styling entry got the
+  same treatment: it claimed no workaround existed, which the above now closes.
+
+### Documented
+
+- **AI Audio Assistant has no scripting method** — logged with the reason, which
+  is *not* that it is a menu command: the API has no generic menu-invocation
+  hook, so scriptability is per-feature, and `DetectSceneCuts`, `Stabilize`,
+  `SmartReframe` and `TranscribeAudio` are all menu commands that do have
+  methods. For a repeatable mix, save the Assistant's result as a Fairlight
+  preset once and apply it per-timeline (issues #127, #128).
+
 ## What's New in v2.81.0
 
 One render bug where every readback agreed and the file disagreed, plus the two

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.81.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.82.1-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)

package/docs/reference/api-limitations.md

@@ -12,7 +12,7 @@ that none exists).
 
 **Verified on:** DaVinci Resolve Studio 21.0.2
 
-**Totals:** 25 missing capabilities, 29 bugs / unreliable behaviors.
+**Totals:** 27 missing capabilities, 30 bugs / unreliable behaviors.
 
 The authoritative source is the runtime-queryable `api_truth` ledger
 (`resolve_control api_truth "<query>"`); this document is generated from
@@ -131,10 +131,17 @@ equivalent, blocking full automation.
 ### Fairlight audio levels / pan / EQ / automation / FairlightFX
 
 - **Object:** `TimelineItem / Timeline`
-- **Behavior:** There is no API to set clip or track volume, pan, EQ, audio automation, or to add/configure FairlightFX. SetProperty covers video transform only; the audio surface is read-only (GetSourceAudioChannelMapping, GetAudioMapping, voice isolation). Verified via dir() + SetProperty docs AND by live mutating attempt on 21.0.0: SetProperty('Volume'|'Level'|'Gain'|'AudioVolume', 0) all return False (note 'Pan' is the VIDEO transform key, not audio pan, so it misleadingly succeeds).
-- **Workaround / current handling:** Mix in the Fairlight UI; only voice-isolation state and channel-mapping reads are scriptable.
+- **Behavior:** There is no API to set clip or track volume, pan, EQ, audio automation, or to add/configure FairlightFX. SetProperty covers video transform only; the audio surface is read-only (GetSourceAudioChannelMapping, GetAudioMapping, voice isolation). Verified via dir() + SetProperty docs AND by live mutating attempt on 21.0.0: SetProperty('Volume'|'Level'|'Gain'|'AudioVolume', 0) all return False (note 'Pan' is the VIDEO transform key, not audio pan, so it misleadingly succeeds). The gap is PER-PARAMETER control specifically: a whole saved mix CAN be applied wholesale via Project.ApplyFairlightPresetToCurrentTimeline(name), with the available names from Resolve.GetFairlightPresets() — so 'no Fairlight write path exists' would be too strong. Both methods require Resolve 20.2.2+; on 19.1.3 they are absent (confirmed live 2026-08-06), so on older builds the per-parameter gap really is the whole story.
+- **Workaround / current handling:** To reapply a known mix, save it once as a Fairlight preset in the UI and apply it per-timeline with ApplyFairlightPresetToCurrentTimeline (exposed as resolve_control get_fairlight_presets + project_settings apply_fairlight_preset). Dial individual levels/pan/EQ/automation/FairlightFX in the Fairlight UI; beyond presets, only voice-isolation state and channel-mapping reads are scriptable.
 - **Tags:** missing-method, audio, fairlight
 
+### AI Audio Assistant (one-click timeline auto-mix)
+
+- **Object:** `Timeline / Project`
+- **Behavior:** The Fairlight AI Audio Assistant — which analyses a timeline and generates a balanced dialogue/music/effects mix — has no scripting method. Nothing matching it appears in the Resolve scripting API reference or in a dir() audit of Resolve, Project, Timeline or TimelineItem. Note this is NOT because it is a menu command: the API has no generic menu-invocation hook at all, so scriptability is per-feature, and plenty of menu commands DO have methods (DetectSceneCuts, Stabilize, SmartReframe, CreateMagicMask, TranscribeAudio, RemoveMotionBlur, AnalyzeForIntellisearch). It is compounded by the per-parameter Fairlight gap above: even the mix it produces cannot be read back or reconstructed clip-by-clip.
+- **Workaround / current handling:** No way to trigger it from a script. For a repeatable mix, run the Assistant once in the UI, save the result as a Fairlight preset, then apply that preset per-timeline with project_settings apply_fairlight_preset — content-adaptive per run is not achievable, a consistent template mix is.
+- **Tags:** missing-method, audio, fairlight, ai, auto-mix
+
 ### Proxy / optimized-media generation
 
 - **Object:** `MediaPoolItem`
@@ -175,7 +182,7 @@ equivalent, blocking full automation.
 
 - **Object:** `TimelineItem / Timeline / Project`
 - **Behavior:** There is no API method to set or query subtitle font family, font size, text color, background color, outline, shadow, position, alignment, or to apply/query subtitle style presets. TimelineItem.GetProperty() on subtitle items returns only transform/composite keys. Timeline.GetSetting() and Project.GetSetting() return None for all probed subtitle-style keys (e.g. 'subtitleFontName', 'subtitleFontSize', 'subtitleTextColor', 'subtitleBackgroundColor', 'subtitlePosition', 'subtitleAlignment', 'subtitlePreset', 'subtitleStyle'). Verified via dir(), GetProperty(), and GetSetting() on Resolve 21.0.0.48.
-- **Workaround / current handling:** No workaround exists — subtitle styling is UI-only. Burn-in overlays via Fusion titles are a visual alternative but do not produce proper subtitle tracks.
+- **Workaround / current handling:** No API workaround exists, but the style IS reachable below the API: it lives in Sm2TiTrack.FieldsBlob for Type=2 tracks, as an EffectFiltersBA payload whose effect 136 carries a Qt QFont descriptor (param 18) and a normalised position vector (param 17). Exposed as project_db list_subtitle_styles / set_subtitle_style (font family/size/weight/italic + position). Confirmed live on Studio 19.1.3 (2026-08-06): Resolve opens a patched track and re-serialises it back to its own zstd form with the patched values intact, so it genuinely parses the write. Caveats: whole-TRACK style not per-caption, project must be CLOSED, Resolve must be fully quit and relaunched afterwards, and the track must already carry a style blob (a freshly added subtitle track has none until it is styled once in the UI). Burn-in overlays via Fusion titles remain a visual alternative but do not produce subtitle tracks.
 - **Tags:** missing-method, subtitle, style, preset
 
 ### Speech recognition engine selection and SRT import
@@ -215,6 +222,15 @@ equivalent, blocking full automation.
 - **Workaround / current handling:** SetCurrentFolder to the target bin first (media_pool set_current_folder), import, then restore the previous current folder if it matters.
 - **Tags:** media-pool, import
 
+### SetClipColor (undocumented value space; marker constants are a decoy)
+
+- **Object:** `TimelineItem / MediaPoolItem`
+- **Signature:** `(colorName) -> bool`
+- **Behavior:** SetClipColor accepts exactly 16 names — the Edit-page clip-colour palette — and refuses everything else with a bare False, no exception and no other signal. Enumerated live on Studio 19.1.3.7 (2026-08-06) against both objects; the accepted set is IDENTICAL on TimelineItem and MediaPoolItem: Orange, Apricot, Yellow, Lime, Olive, Green, Teal, Navy, Blue, Purple, Violet, Pink, Tan, Beige, Brown, Chocolate. The empty string is refused too. The trap is that the scripting reference documents colorName as a bare string with no enumerated values, while exporting the MARKER palette as constants (resolve.MARKER_ROSE, resolve.MARKER_FUCHSIA, ...) — so the only colour vocabulary reachable from the API surface is the wrong one. Cyan, Red, Fuchsia, Rose, Lavender, Sky, Mint, Lemon, Sand, Cocoa and Cream are all marker-only and all refused. Five names overlap both palettes (Blue, Green, Yellow, Pink, Purple), which is why the decoy survives: reasoning from the marker constants scores 5 of 16 and looks like the right vocabulary with a few gaps.
+- **Workaround / current handling:** Pass only the 16 clip-colour names; on False, treat it as an invalid name rather than an item/lock/page problem. The set is pinned in utils/clip_colors.py and named in the refusal remediation, but deliberately NOT enforced — it was measured on one build and a later Resolve could extend it.
+- **Reference:** [issue #124](https://github.com/samuelgursky/davinci-resolve-mcp/issues/124)
+- **Tags:** timeline-item, media-pool, silent-failure, undocumented-enum
+
 ### Project.SetCurrentRenderFormatAndCodec
 
 - **Object:** `Project`
@@ -436,6 +452,15 @@ values, or automation-hostile modal prompts.
 - **Reference:** [issue #59](https://github.com/samuelgursky/davinci-resolve-mcp/issues/59)
 - **Tags:** render, deliver, silent-failure, id-vs-label
 
+### TimelineItem.SetClipColor on generator/title items
+
+- **Object:** `TimelineItem`
+- **Signature:** `(colorName) -> bool`
+- **Behavior:** On a generator or title item SetClipColor returns True with a VALID colour name and the colour does not persist — GetClipColor still reads '' immediately afterwards, and ClearClipColor changes nothing because there is nothing to clear. Measured on Studio 19.1.3.7 (2026-08-06) on a Solid Color generator. A media-backed item on the SAME timeline in the same session persists correctly (SetClipColor('Teal') -> True, GetClipColor -> 'Teal'), so the bool is honest for some items and a lie for others, with nothing in the return value to tell them apart. A timeline item's colour is also independent of its backing MediaPoolItem's: colouring the item leaves the pool clip at ''.
+- **Workaround / current handling:** Never trust the bool alone — read GetClipColor back and compare. To mark a generator or title, use a timeline marker at its start instead; markers read back reliably.
+- **Reference:** [issue #124](https://github.com/samuelgursky/davinci-resolve-mcp/issues/124)
+- **Tags:** timeline-item, silent-failure, generator, readback-lies
+
 ### Project.SetRenderSettings (inherits the loaded preset)
 
 - **Object:** `Project`

package/install.py

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

package/package.json

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

package/resolve-advanced/README.md

@@ -83,6 +83,9 @@ Each dispatches on an `action`. Highlights:
   reverse-clip DB repair, sequence lineage store + diff, per-cut frame QC.
 - **`color_trace`** — cross-project clip matching → a trace plan for carrying grades across a re-conform.
 - **`project_read` / `project_db`** — read/patch the Resolve project DB (SQLite or Postgres).
+  Includes `list_subtitle_styles` / `set_subtitle_style` — caption font family/size/weight/italic
+  and normalised position, which the scripting API cannot touch at all. Whole-track (not
+  per-caption); project must be CLOSED and Resolve fully quit + relaunched afterwards.
 - **`pipeline`** — the DB-as-truth pipeline foundation (see below).
 - **`deliverable`** — deliverable QC / compliance: `deliverable_qc` (ffprobe a render vs its spec →
   pass/fail per field), `loudness_qc` (ebur128 LUFS/true-peak/LRA), `reframe_blanking_check`,

package/resolve-advanced/server/tools/project_db.mjs

@@ -12,6 +12,9 @@
  * set_clip_marks — Sm2MpMedia.MarkIn/MarkOut (set clip in/out points)
  * relayout_node_graphs — rewrite node x/y in every graded ListMgt::LmVersion Body
  *   (whole-project "Cleanup Node Graph"; the UI command has NO scripting API)
+ * list_subtitle_styles — read caption style per subtitle track (font + position)
+ * set_subtitle_style — patch Sm2TiTrack.FieldsBlob caption style (font family/size/
+ *   italic/weight + normalised position). The API exposes NO subtitle styling at all.
  */
 
 import { z } from 'zod';
@@ -52,6 +55,33 @@ const relayoutSchema = z.object({
   iConfirmProjectClosed: confirm,
 });
 
+const listSubtitleStylesSchema = z.object({ ...dbTarget });
+const setSubtitleStyleSchema = z.object({
+  ...dbTarget,
+  timeline: z.string().describe('Timeline name carrying the subtitle track'),
+  track: z.number().int().min(1).optional().describe('1-based subtitle track index within that timeline (default 1)'),
+  family: z.string().optional().describe('Font family, e.g. "Montserrat"'),
+  pointSize: z.number().int().optional().describe('Font point size'),
+  weight: z.number().int().optional().describe('Qt font weight (50 = Regular, 75 = Bold)'),
+  italic: z.boolean().optional(),
+  styleName: z.string().optional().describe('Qt style name, e.g. "Regular" / "Bold" / "Oblique"'),
+  positionX: z.number().optional().describe('Normalised X (0-1, 0.5 = centre)'),
+  positionY: z.number().optional().describe('Normalised Y (0-1)'),
+  dryRun: z.boolean().optional().describe('Report the decoded before/after without writing'),
+  iConfirmProjectClosed: confirm,
+});
+
+// Subtitle tracks are Sm2TiTrack rows with Type = 2, linked to their timeline via
+// Sm2TiTrack.Sequence -> Sm2Sequence.Sm2Sequence_id -> Sm2Timeline. (Note the join
+// column is `Sequence`, NOT the same-table `Sm2Sequence_id`, which is null here.)
+const SUBTITLE_TRACK_QUERY = `
+  SELECT tl.Name AS timeline, tr.Sm2TiTrack_id AS id, tr.FieldsBlob AS blob
+  FROM Sm2TiTrack tr
+  JOIN Sm2Sequence sq ON tr.Sequence = sq.Sm2Sequence_id
+  JOIN Sm2Timeline tl ON sq.Sm2Timeline_id = tl.Sm2Timeline_id
+  WHERE tr.Type = 2
+  ORDER BY tl.Name, tr.rowid`;
+
 function selectOne(db, table, col, value) {
   const rows = db.prepare(`SELECT rowid AS rid, Name FROM ${table} WHERE Name = ?`).all(value);
   if (!rows.length) throw new Error(`no ${table} named "${value}"`);
@@ -62,7 +92,7 @@ function selectOne(db, table, col, value) {
 export const projectDbTool = {
   name: 'project_db',
   description:
-    'Beyond-the-API live Project.db patches (plain columns) — closes gaps the scripting API cannot. Project must be CLOSED (auto-backup + schema guard + verify). Actions: list_folders, rename_folder (no RenameSubFolder API), set_folder_color, list_clips, set_clip_marks, relayout_node_graphs (whole-project Cleanup Node Graph — rewrites node x/y in every graded version Body; grade content untouched; REQUIRES full Resolve quit+relaunch after patching, it caches open projects in memory). Needs optional better-sqlite3.',
+    'Beyond-the-API live Project.db patches (plain columns) — closes gaps the scripting API cannot. Project must be CLOSED (auto-backup + schema guard + verify). Actions: list_folders, rename_folder (no RenameSubFolder API), set_folder_color, list_clips, set_clip_marks, relayout_node_graphs (whole-project Cleanup Node Graph — rewrites node x/y in every graded version Body; grade content untouched; REQUIRES full Resolve quit+relaunch after patching, it caches open projects in memory), list_subtitle_styles, set_subtitle_style (caption font family/size/italic/weight + normalised position — the scripting API exposes NO subtitle styling; whole-track, not per-caption; same quit+relaunch requirement). Needs optional better-sqlite3.',
   async handler({ action, args }) {
     if (action === 'list_folders') {
       const p = listFoldersSchema.parse(args);
@@ -195,6 +225,104 @@ export const projectDbTool = {
         db.close();
       }
     }
+    if (action === 'list_subtitle_styles') {
+      const p = listSubtitleStylesSchema.parse(args);
+      const style = require('../../vendor/drp-format/subtitle-style.js');
+      const db = openGuarded(resolveDbPath(p), { table: 'Sm2TiTrack', column: 'FieldsBlob' });
+      try {
+        const counts = new Map();
+        const tracks = [];
+        for (const row of db.prepare(SUBTITLE_TRACK_QUERY).all()) {
+          const n = (counts.get(row.timeline) || 0) + 1;
+          counts.set(row.timeline, n);
+          const entry = { timeline: row.timeline, track: n };
+          try {
+            const dec = style.decodeSubtitleStyle(Buffer.from(row.blob));
+            entry.styled = dec.styled;
+            if (dec.styled) {
+              entry.font = dec.font && {
+                family: dec.font.family,
+                pointSize: dec.font.pointSize,
+                weight: dec.font.weight,
+                italic: dec.font.italic,
+                styleName: dec.font.styleName,
+              };
+              entry.position = dec.position;
+              entry.opaqueParams = dec.opaque.length;
+            }
+          } catch (e) {
+            // Report an undecodable track rather than failing the whole listing.
+            entry.error = e.message;
+          }
+          tracks.push(entry);
+        }
+        return {
+          tracks,
+          note: tracks.some((t) => t.styled === false)
+            ? 'Tracks with styled:false carry no style blob (Resolve writes a NumLayers-only stub until the track is styled once in the UI); set_subtitle_style cannot patch those.'
+            : undefined,
+        };
+      } finally {
+        db.close();
+      }
+    }
+    if (action === 'set_subtitle_style') {
+      const p = setSubtitleStyleSchema.parse(args);
+      const style = require('../../vendor/drp-format/subtitle-style.js');
+      const changes = {};
+      for (const k of ['family', 'pointSize', 'weight', 'italic', 'styleName']) {
+        if (p[k] != null) changes[k] = p[k];
+      }
+      if ((p.positionX == null) !== (p.positionY == null)) {
+        throw new Error('positionX and positionY must be given together');
+      }
+      if (p.positionX != null) changes.position = { x: p.positionX, y: p.positionY };
+      if (!Object.keys(changes).length) throw new Error('nothing to change — pass family/pointSize/weight/italic/styleName and/or positionX+positionY');
+
+      const write = !p.dryRun;
+      if (write) requireClosed(p);
+      const dbPath = resolveDbPath(p);
+      const bak = write ? backup(dbPath) : null;
+      const db = openGuarded(dbPath, { writable: write, table: 'Sm2TiTrack', column: 'FieldsBlob' });
+      try {
+        const wanted = p.track || 1;
+        let seen = 0;
+        let target = null;
+        for (const row of db.prepare(SUBTITLE_TRACK_QUERY).all()) {
+          if (row.timeline !== p.timeline) continue;
+          seen += 1;
+          if (seen === wanted) { target = row; break; }
+        }
+        if (!target) {
+          throw new Error(`timeline "${p.timeline}" has no subtitle track ${wanted} (found ${seen}) — run list_subtitle_styles`);
+        }
+        const before = style.decodeSubtitleStyle(Buffer.from(target.blob));
+        const patched = style.encodeSubtitleStyle(Buffer.from(target.blob), changes);
+        const after = style.decodeSubtitleStyle(patched);
+        if (write) {
+          db.prepare('UPDATE Sm2TiTrack SET FieldsBlob = ? WHERE Sm2TiTrack_id = ?').run(patched, target.id);
+          const back = db.prepare('SELECT FieldsBlob FROM Sm2TiTrack WHERE Sm2TiTrack_id = ?').get(target.id);
+          const verify = style.decodeSubtitleStyle(Buffer.from(back.FieldsBlob));
+          if (verify.font.raw !== after.font.raw || JSON.stringify(verify.position) !== JSON.stringify(after.position)) {
+            throw new Error(`read-back verify failed on track ${target.id} — restore from backup ${bak}`);
+          }
+        }
+        return {
+          dryRun: !write,
+          backup: bak,
+          timeline: p.timeline,
+          track: wanted,
+          before: { font: before.font && before.font.raw, position: before.position },
+          after: { font: after.font && after.font.raw, position: after.position },
+          opaqueParamsPreserved: JSON.stringify(before.opaque) === JSON.stringify(after.opaque),
+          note: write
+            ? 'Resolve caches open projects IN MEMORY: fully QUIT Resolve and relaunch before reopening this project, or the patched style will not be visible (and an oversave could revert it). This is a whole-TRACK style, not per-caption.'
+            : 'Dry run — nothing written. Re-run with dryRun:false + iConfirmProjectClosed:true (project CLOSED in Resolve).',
+        };
+      } finally {
+        db.close();
+      }
+    }
     throw new Error(`Unknown project_db action: ${action}`);
   },
 };

package/resolve-advanced/vendor/drp-format/subtitle-style.js

@@ -0,0 +1,416 @@
+/**
+ * DaVinci Resolve subtitle-track style codec.
+ *
+ * Reads and writes the caption style Resolve stores on a SUBTITLE track
+ * (`Sm2TiTrack` rows with `Type = 2`). The scripting API exposes none of this:
+ * subtitle TimelineItems return only the 21 transform/composite properties, and
+ * `Timeline`/`Project.GetSetting()` return null for every subtitle-style key. See
+ * the `Subtitle track styling and presets` entry in src/utils/api_truth.py.
+ *
+ * Container chain (outermost first):
+ *
+ *   Sm2TiTrack.FieldsBlob        keyed-dict (keyed-dict.js) — { NumLayers, EffectFiltersBA }
+ *     -> EffectFiltersBA         [u32 version=2][u32 payloadLen][u8 0x80|0x81][payload]
+ *          0x80 = raw protobuf, 0x81 = compressed (Resolve 21 writes ZSTD)
+ *       -> protobuf              repeated f1 = effect, each:
+ *                                  f1 varint  effect id (136 carries the text style)
+ *                                  f9 LEN     parameter, repeated and POSITIONAL —
+ *                                             empty f9 entries are placeholders and
+ *                                             MUST be preserved to keep param order
+ *                                    f1 varint param id
+ *                                    f3 LEN    value wrapper -> f1 LEN -> one of:
+ *                                                f1 varint  integer
+ *                                                f3 LEN     string
+ *                                                f2 fixed64 double  (LITTLE-endian)
+ *                                                f7 LEN     double vector (BIG-endian)
+ *
+ * Note the endianness split: scalar doubles (f2) are little-endian, but the f7
+ * double vector used by the position parameter is big-endian. Both were confirmed
+ * against live Resolve 21 projects — reading either one with the wrong order
+ * yields plausible-looking garbage (~1e-319), so this is worth not "fixing".
+ *
+ * Only two parameters of effect 136 are given names here, because only these two
+ * are self-describing:
+ *   param 18 — Qt QFont::toString() descriptor, e.g.
+ *              "Helvetica,13,-1,5,50,0,0,0,0,0,Regular"
+ *              (family, pointSize, pixelSize, styleHint, weight, italic,
+ *               underline, strikeOut, fixedPitch, rawMode, styleName)
+ *   param 17 — normalised position vector [x, y], origin top-left, e.g. [0.5, 0.109]
+ *
+ * Every other parameter (19, 34, 142, and effects 16/54/56) round-trips untouched
+ * and is reported under `opaque`. They vary across real projects but their meaning
+ * has NOT been correlated against the UI, so they are deliberately left unlabelled
+ * rather than guessed at.
+ *
+ * @module drp-format/subtitle-style
+ */
+
+const { decodeKeyedDict, encodeKeyedDict } = require('./keyed-dict.js');
+
+let fzstd = null;
+try { fzstd = require('fzstd'); } catch (e) { /* optional; 0x81 zstd payloads need it */ }
+
+const TEXT_STYLE_EFFECT = 136;
+const PARAM_FONT = 18;
+const PARAM_POSITION = 17;
+
+const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+
+// ---------------------------------------------------------------------------
+// protobuf primitives (field-preserving: we never drop unknown fields)
+// ---------------------------------------------------------------------------
+
+function readVarint(buf, off) {
+  let value = 0n;
+  let shift = 0n;
+  let n = 0;
+  while (off + n < buf.length) {
+    const byte = buf[off + n];
+    value |= BigInt(byte & 0x7f) << shift;
+    n += 1;
+    if (!(byte & 0x80)) return { value: Number(value), bytesRead: n };
+    shift += 7n;
+  }
+  throw new Error('truncated varint');
+}
+
+function writeVarint(value) {
+  const bytes = [];
+  let remaining = value;
+  while (remaining > 0x7f) {
+    bytes.push((remaining & 0x7f) | 0x80);
+    remaining = Math.floor(remaining / 128);
+  }
+  bytes.push(remaining & 0x7f);
+  return Buffer.from(bytes);
+}
+
+/**
+ * Parse a protobuf message into a flat list of {field, wire, ...} records.
+ * Length-delimited payloads are kept as raw Buffers so unknown structure
+ * survives a re-encode byte-for-byte.
+ */
+function parseMessage(buf) {
+  const out = [];
+  let off = 0;
+  while (off < buf.length) {
+    const tag = readVarint(buf, off);
+    off += tag.bytesRead;
+    const field = tag.value >> 3;
+    const wire = tag.value & 7;
+    if (wire === 0) {
+      const v = readVarint(buf, off);
+      off += v.bytesRead;
+      out.push({ field, wire, value: v.value });
+    } else if (wire === 1) {
+      out.push({ field, wire, bytes: buf.slice(off, off + 8) });
+      off += 8;
+    } else if (wire === 2) {
+      const len = readVarint(buf, off);
+      off += len.bytesRead;
+      out.push({ field, wire, bytes: buf.slice(off, off + len.value) });
+      off += len.value;
+    } else if (wire === 5) {
+      out.push({ field, wire, bytes: buf.slice(off, off + 4) });
+      off += 4;
+    } else {
+      throw new Error(`unsupported protobuf wire type ${wire} at offset ${off}`);
+    }
+  }
+  return out;
+}
+
+function serializeMessage(records) {
+  const parts = [];
+  for (const rec of records) {
+    parts.push(writeVarint((rec.field << 3) | rec.wire));
+    if (rec.wire === 0) {
+      parts.push(writeVarint(rec.value));
+    } else if (rec.wire === 2) {
+      parts.push(writeVarint(rec.bytes.length));
+      parts.push(rec.bytes);
+    } else {
+      parts.push(rec.bytes);
+    }
+  }
+  return Buffer.concat(parts);
+}
+
+// ---------------------------------------------------------------------------
+// EffectFiltersBA envelope
+// ---------------------------------------------------------------------------
+
+function unwrapEffectFilters(raw) {
+  if (raw.length < 9) throw new Error('EffectFiltersBA too short');
+  const version = raw.readUInt32BE(0);
+  const declared = raw.readUInt32BE(4);
+  const marker = raw[8];
+  const payload = raw.slice(9);
+  if (declared !== payload.length + 1) {
+    throw new Error(`EffectFiltersBA length mismatch: declared ${declared}, payload ${payload.length + 1}`);
+  }
+  if (marker === 0x80) return { version, marker, protobuf: payload };
+  if (marker === 0x81) {
+    if (!payload.slice(0, 4).equals(ZSTD_MAGIC)) {
+      throw new Error('EffectFiltersBA 0x81 payload is not a zstd frame');
+    }
+    if (!fzstd) throw new Error("EffectFiltersBA 0x81 payload is zstd; optional dep 'fzstd' is required to decode");
+    return { version, marker, protobuf: Buffer.from(fzstd.decompress(new Uint8Array(payload))) };
+  }
+  throw new Error(`unknown EffectFiltersBA payload marker 0x${marker.toString(16)}`);
+}
+
+/**
+ * Re-wrap a protobuf payload as EffectFiltersBA.
+ *
+ * Always emits the UNCOMPRESSED 0x80 form. This avoids depending on a zstd
+ * *compressor* (the bundled fzstd is decompress-only); the cost is a larger
+ * blob, which does not matter here.
+ *
+ * Confirmed live against Resolve Studio 19.1.3 (2026-08-06): a subtitle track patched with
+ * a 0x80 payload opens without error, and once Resolve next re-serialises that
+ * track it writes the style back out as 0x81 zstd with the font descriptor and
+ * position preserved exactly — i.e. Resolve genuinely parses the 0x80 form into
+ * its in-memory model rather than passing the bytes through untouched.
+ */
+function wrapEffectFilters(protobuf, version = 2) {
+  const head = Buffer.alloc(9);
+  head.writeUInt32BE(version, 0);
+  head.writeUInt32BE(protobuf.length + 1, 4);
+  head[8] = 0x80;
+  return Buffer.concat([head, protobuf]);
+}
+
+// ---------------------------------------------------------------------------
+// parameter access
+// ---------------------------------------------------------------------------
+
+/** Split one effect into { idRecord, params: [{record, id, wrapper}] , others } */
+function readEffect(effectBytes) {
+  const records = parseMessage(effectBytes);
+  const params = [];
+  for (const rec of records) {
+    if (rec.field !== 9 || rec.wire !== 2 || rec.bytes.length === 0) continue;
+    const inner = parseMessage(rec.bytes);
+    const idRec = inner.find((r) => r.field === 1 && r.wire === 0);
+    if (!idRec) continue;
+    params.push({ record: rec, id: idRec.value, inner });
+  }
+  const idRec = records.find((r) => r.field === 1 && r.wire === 0);
+  return { records, effectId: idRec ? idRec.value : null, params };
+}
+
+/** Decode the value wrapper (f3 -> f1 -> typed leaf) into a JS value. */
+function readParamValue(wrapperBytes) {
+  const outer = parseMessage(wrapperBytes).find((r) => r.field === 1 && r.wire === 2);
+  if (!outer) return null;
+  const leaves = parseMessage(outer.bytes);
+  const result = {};
+  for (const leaf of leaves) {
+    if (leaf.field === 1 && leaf.wire === 0) result.int = leaf.value;
+    else if (leaf.field === 3 && leaf.wire === 2) result.string = leaf.bytes.toString('utf8');
+    else if (leaf.field === 2 && leaf.wire === 1) result.double = leaf.bytes.readDoubleLE(0);
+    else if (leaf.field === 7 && leaf.wire === 2) {
+      // BIG-endian double vector — see module note on the endianness split.
+      const vec = [];
+      for (let i = 0; i + 8 <= leaf.bytes.length; i += 8) vec.push(leaf.bytes.readDoubleBE(i));
+      result.vector = vec;
+    }
+  }
+  return Object.keys(result).length ? result : null;
+}
+
+/** Rebuild a value wrapper, replacing the string leaf. */
+function writeStringParam(wrapperBytes, text) {
+  const outerRecords = parseMessage(wrapperBytes);
+  const outer = outerRecords.find((r) => r.field === 1 && r.wire === 2);
+  if (!outer) throw new Error('parameter wrapper has no inner message');
+  const leaves = parseMessage(outer.bytes);
+  const target = leaves.find((l) => l.field === 3 && l.wire === 2);
+  if (!target) throw new Error('parameter has no string leaf to replace');
+  target.bytes = Buffer.from(text, 'utf8');
+  outer.bytes = serializeMessage(leaves);
+  return serializeMessage(outerRecords);
+}
+
+/** Rebuild a value wrapper, replacing the big-endian double vector. */
+function writeVectorParam(wrapperBytes, values) {
+  const outerRecords = parseMessage(wrapperBytes);
+  const outer = outerRecords.find((r) => r.field === 1 && r.wire === 2);
+  if (!outer) throw new Error('parameter wrapper has no inner message');
+  const leaves = parseMessage(outer.bytes);
+  const target = leaves.find((l) => l.field === 7 && l.wire === 2);
+  if (!target) throw new Error('parameter has no vector leaf to replace');
+  if (values.length * 8 !== target.bytes.length) {
+    throw new Error(`vector arity mismatch: existing ${target.bytes.length / 8} values, given ${values.length}`);
+  }
+  const buf = Buffer.alloc(values.length * 8);
+  values.forEach((v, i) => buf.writeDoubleBE(v, i * 8));
+  target.bytes = buf;
+  outer.bytes = serializeMessage(leaves);
+  return serializeMessage(outerRecords);
+}
+
+// ---------------------------------------------------------------------------
+// QFont descriptor
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a Qt QFont::toString() descriptor.
+ * Fields after the family are positional; unknown trailing fields are kept
+ * verbatim so a re-serialise is lossless.
+ */
+function parseFontDescriptor(descriptor) {
+  const parts = String(descriptor).split(',');
+  return {
+    family: parts[0],
+    pointSize: parts.length > 1 ? Number(parts[1]) : null,
+    pixelSize: parts.length > 2 ? Number(parts[2]) : null,
+    styleHint: parts.length > 3 ? Number(parts[3]) : null,
+    weight: parts.length > 4 ? Number(parts[4]) : null,
+    italic: parts.length > 5 ? parts[5] === '1' : null,
+    styleName: parts.length > 10 ? parts[10] : null,
+    raw: descriptor,
+    _parts: parts,
+  };
+}
+
+function buildFontDescriptor(parsed, changes) {
+  const parts = parsed._parts.slice();
+  if (changes.family != null) parts[0] = String(changes.family);
+  if (changes.pointSize != null && parts.length > 1) parts[1] = String(changes.pointSize);
+  if (changes.weight != null && parts.length > 4) parts[4] = String(changes.weight);
+  if (changes.italic != null && parts.length > 5) parts[5] = changes.italic ? '1' : '0';
+  if (changes.styleName != null && parts.length > 10) parts[10] = String(changes.styleName);
+  return parts.join(',');
+}
+
+// ---------------------------------------------------------------------------
+// public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Decode the caption style from an Sm2TiTrack.FieldsBlob.
+ *
+ * @param {Buffer|string} fieldsBlob - raw blob or hex string
+ * @returns {{styled: boolean, font: object|null, position: {x: number, y: number}|null,
+ *            opaque: Array, effects: Array}}
+ *   `styled: false` means the track carries no EffectFiltersBA at all (Resolve
+ *   writes a ~39-byte NumLayers-only stub for an unstyled subtitle track).
+ */
+function decodeSubtitleStyle(fieldsBlob) {
+  const buf = Buffer.isBuffer(fieldsBlob) ? fieldsBlob : Buffer.from(fieldsBlob, 'hex');
+  const dict = decodeKeyedDict(buf);
+  const entry = dict.entries.find((e) => e.key === 'EffectFiltersBA');
+  if (!entry || !entry.value) {
+    return { styled: false, font: null, position: null, opaque: [], effects: [] };
+  }
+  const { protobuf } = unwrapEffectFilters(Buffer.from(entry.value, 'hex'));
+  const effects = parseMessage(protobuf).filter((r) => r.field === 1 && r.wire === 2);
+
+  let font = null;
+  let position = null;
+  const opaque = [];
+  const summary = [];
+
+  for (const effectRec of effects) {
+    const effect = readEffect(effectRec.bytes);
+    const paramSummary = [];
+    for (const param of effect.params) {
+      const wrapper = param.inner.find((r) => r.field === 3 && r.wire === 2);
+      const value = wrapper ? readParamValue(wrapper.bytes) : null;
+      paramSummary.push({ id: param.id, value });
+      if (effect.effectId === TEXT_STYLE_EFFECT && param.id === PARAM_FONT && value && value.string) {
+        font = parseFontDescriptor(value.string);
+      } else if (effect.effectId === TEXT_STYLE_EFFECT && param.id === PARAM_POSITION && value && value.vector) {
+        position = { x: value.vector[0], y: value.vector[1] };
+      } else if (value) {
+        opaque.push({ effect: effect.effectId, param: param.id, value });
+      }
+    }
+    summary.push({ effect: effect.effectId, params: paramSummary });
+  }
+  return { styled: true, font, position, opaque, effects: summary };
+}
+
+/**
+ * Return a new FieldsBlob with the caption style modified.
+ *
+ * Only the font descriptor and position are writable; every other parameter and
+ * effect is re-emitted untouched. Throws rather than silently no-op'ing when the
+ * track has no style blob to patch, or when a requested change has no target
+ * parameter — a silent no-op here would read as success.
+ *
+ * @param {Buffer|string} fieldsBlob
+ * @param {{family?: string, pointSize?: number, weight?: number, italic?: boolean,
+ *          styleName?: string, position?: {x: number, y: number}}} changes
+ * @returns {Buffer} new FieldsBlob
+ */
+function encodeSubtitleStyle(fieldsBlob, changes = {}) {
+  const buf = Buffer.isBuffer(fieldsBlob) ? fieldsBlob : Buffer.from(fieldsBlob, 'hex');
+  const dict = decodeKeyedDict(buf);
+  const entry = dict.entries.find((e) => e.key === 'EffectFiltersBA');
+  if (!entry || !entry.value) {
+    throw new Error(
+      'track has no EffectFiltersBA — it is an unstyled subtitle track; ' +
+      'style it once in the Resolve UI so a style blob exists to patch',
+    );
+  }
+  const envelope = unwrapEffectFilters(Buffer.from(entry.value, 'hex'));
+  const records = parseMessage(envelope.protobuf);
+
+  const wantsFont = changes.family != null || changes.pointSize != null ||
+    changes.weight != null || changes.italic != null || changes.styleName != null;
+  const wantsPosition = changes.position != null;
+  let fontDone = false;
+  let positionDone = false;
+
+  for (const effectRec of records) {
+    if (effectRec.field !== 1 || effectRec.wire !== 2) continue;
+    const effect = readEffect(effectRec.bytes);
+    if (effect.effectId !== TEXT_STYLE_EFFECT) continue;
+    let touched = false;
+    for (const param of effect.params) {
+      const wrapper = param.inner.find((r) => r.field === 3 && r.wire === 2);
+      if (!wrapper) continue;
+      if (wantsFont && param.id === PARAM_FONT) {
+        const current = readParamValue(wrapper.bytes);
+        if (!current || !current.string) continue;
+        const next = buildFontDescriptor(parseFontDescriptor(current.string), changes);
+        wrapper.bytes = writeStringParam(wrapper.bytes, next);
+        param.record.bytes = serializeMessage(param.inner);
+        fontDone = true;
+        touched = true;
+      } else if (wantsPosition && param.id === PARAM_POSITION) {
+        const current = readParamValue(wrapper.bytes);
+        if (!current || !current.vector) continue;
+        wrapper.bytes = writeVectorParam(wrapper.bytes, [changes.position.x, changes.position.y]);
+        param.record.bytes = serializeMessage(param.inner);
+        positionDone = true;
+        touched = true;
+      }
+    }
+    if (touched) effectRec.bytes = serializeMessage(effect.records);
+  }
+
+  if (wantsFont && !fontDone) throw new Error(`no font parameter (${PARAM_FONT}) found on effect ${TEXT_STYLE_EFFECT}`);
+  if (wantsPosition && !positionDone) throw new Error(`no position parameter (${PARAM_POSITION}) found on effect ${TEXT_STYLE_EFFECT}`);
+
+  entry.value = wrapEffectFilters(serializeMessage(records), envelope.version).toString('hex');
+  return encodeKeyedDict(dict);
+}
+
+module.exports = {
+  decodeSubtitleStyle,
+  encodeSubtitleStyle,
+  // exposed for tests and for callers needing the lower layers
+  parseMessage,
+  serializeMessage,
+  unwrapEffectFilters,
+  wrapEffectFilters,
+  parseFontDescriptor,
+  buildFontDescriptor,
+  TEXT_STYLE_EFFECT,
+  PARAM_FONT,
+  PARAM_POSITION,
+};

package/src/granular/common.py

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

package/src/granular/timeline_item.py

@@ -1,6 +1,7 @@
 """Timeline item property, keyframe, and clip-level tools."""
 
 from src.granular.common import *  # noqa: F401,F403
+from src.utils.clip_colors import clip_color_refusal
 
 resolve = ResolveProxy()
 
@@ -1528,7 +1529,32 @@ def ti_set_clip_color(color: str, item_index: int = 0, track_type: str = "video"
     item, err = _get_timeline_item(track_type, track_index, item_index)
     if err:
         return err
-    return {"success": bool(item.SetClipColor(color))}
+    returned = bool(item.SetClipColor(color))
+    readback = item.GetClipColor() or ""
+    if not returned:
+        refusal = clip_color_refusal(color)
+        return {
+            "success": False,
+            "color": color,
+            "error": f"SetClipColor refused '{color}'",
+            "reason": refusal["reason"],
+            "remediation": refusal["remediation"],
+            "valid_colors": refusal["state"]["valid_colors"],
+        }
+    if readback != color:
+        # Generator and title items take the call, return True, and drop the
+        # colour (issue #124, Studio 19.1.3.7). Media-backed items persist.
+        return {
+            "success": False,
+            "color": color,
+            "readback": readback,
+            "error": "SetClipColor returned True but the colour did not persist",
+            "remediation": (
+                "Generator and title items accept and discard clip colours; colour "
+                "a media-backed item, or use a timeline marker instead."
+            ),
+        }
+    return {"success": True, "color": color, "readback": readback}
 
 
 @mcp.tool()

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.81.0"
+VERSION = "2.82.1"
 
 import base64
 import os
@@ -46,6 +46,7 @@ for p in [current_dir, project_dir]:
 from src.utils.cdl import normalize_cdl_payload
 from src.utils.mcp_stdio import run_fastmcp_stdio
 from src.utils.api_truth import lookup_api_truth, VERIFIED_ON as _API_TRUTH_VERIFIED_ON
+from src.utils import clip_colors as _clip_colors
 from src.utils.contracts import validate as _validate_params
 from src.utils.cut_ir import build_cut_list as _build_cut_list
 from src.utils.page_lock import (
@@ -9006,6 +9007,66 @@ def _safe_int(value: Any, default: int, *, minimum: Optional[int] = None, maximu
     return parsed
 
 
+def _set_clip_color_checked(obj, color, *, kind: str):
+    """SetClipColor, with the bare bool turned into something a caller can act on.
+
+    Two measured failures hide behind that bool (issue #124, enumerated live on
+    Studio 19.1.3.7):
+
+    - A name outside the 16-name Edit-page palette is refused with `False` and
+      nothing else. The marker constants are the only colour vocabulary the
+      scripting reference enumerates, so they are what an agent reaches for, and
+      most of them are refused.
+    - On generator and title items the call returns `True` and the colour does
+      not persist — `GetClipColor` still reads empty afterwards. Media-backed
+      items on the same timeline persist correctly, so the bool is honest for
+      some items and a lie for others.
+
+    So the return value is never trusted on its own: the colour is read back and
+    the response reports what actually stuck.
+    """
+    returned = bool(obj.SetClipColor(color))
+    readback = None
+    if _has_method(obj, "GetClipColor"):
+        try:
+            readback = obj.GetClipColor()
+        except Exception:  # pragma: no cover - defensive; getter is documented
+            readback = None
+    persisted = (readback == color) if readback is not None else None
+
+    if not returned:
+        refusal = _clip_colors.clip_color_refusal(color)
+        return _err(
+            f"SetClipColor refused '{color}' on this {kind}",
+            code="CLIP_COLOR_REJECTED",
+            category="invalid_input",
+            reason=refusal["reason"],
+            remediation=refusal["remediation"],
+            state=refusal["state"],
+        )
+    if persisted is False:
+        # The generator/title case. Reporting success here is the silent lie.
+        return {
+            "success": False,
+            "color": color,
+            "readback": readback,
+            "warnings": [{
+                "code": "CLIP_COLOR_NOT_PERSISTED",
+                "message": (
+                    f"SetClipColor returned True on this {kind} but the colour did "
+                    f"not persist — GetClipColor reads {readback!r}. Measured on "
+                    "generator and title items, which take the call and drop it; "
+                    "media-backed items on the same timeline persist correctly."
+                ),
+                "remediation": (
+                    "Colour a media-backed item, or mark the generator another way "
+                    "(a timeline marker at its start reads back reliably)."
+                ),
+            }],
+        }
+    return {"success": True, "color": color, "readback": readback}
+
+
 def _filter_to_keys(settings: Any, allowed) -> Tuple[Dict[str, Any], list]:
     """Whitelist a settings/options dict to the keys a Resolve API documents.
 
@@ -17783,7 +17844,7 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     elif action == "get_clip_color":
         return {"color": clip.GetClipColor()}
     elif action == "set_clip_color":
-        return {"success": bool(clip.SetClipColor(p["color"]))}
+        return _set_clip_color_checked(clip, p["color"], kind="media pool item")
     elif action == "clear_clip_color":
         return {"success": bool(clip.ClearClipColor())}
     elif action == "link_proxy":
@@ -22251,7 +22312,7 @@ def timeline_item_markers(action: str, params: Optional[Dict[str, Any]] = None)
     elif action == "get_clip_color":
         return {"color": item.GetClipColor()}
     elif action == "set_clip_color":
-        return {"success": bool(item.SetClipColor(p["color"]))}
+        return _set_clip_color_checked(item, p["color"], kind="timeline item")
     elif action == "clear_clip_color":
         return {"success": bool(item.ClearClipColor())}
     return _unknown(action, ["add","get_all","get_by_custom_data","update_custom_data","get_custom_data","delete_by_color","delete_at_frame","delete_by_custom_data","add_flag","get_flags","clear_flags","get_clip_color","set_clip_color","clear_clip_color"])

package/src/utils/api_truth.py

@@ -858,12 +858,49 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "isolation). Verified via dir() + SetProperty docs AND by live "
                    "mutating attempt on 21.0.0: SetProperty('Volume'|'Level'|'Gain'"
                    "|'AudioVolume', 0) all return False (note 'Pan' is the VIDEO "
-                   "transform key, not audio pan, so it misleadingly succeeds).",
-        "recommended": "Mix in the Fairlight UI; only voice-isolation state and "
-                       "channel-mapping reads are scriptable.",
+                   "transform key, not audio pan, so it misleadingly succeeds). "
+                   "The gap is PER-PARAMETER control specifically: a whole saved "
+                   "mix CAN be applied wholesale via "
+                   "Project.ApplyFairlightPresetToCurrentTimeline(name), with the "
+                   "available names from Resolve.GetFairlightPresets() — so "
+                   "'no Fairlight write path exists' would be too strong. Both "
+                   "methods require Resolve 20.2.2+; on 19.1.3 they are absent "
+                   "(confirmed live 2026-08-06), so on older builds the "
+                   "per-parameter gap really is the whole story.",
+        "recommended": "To reapply a known mix, save it once as a Fairlight preset "
+                       "in the UI and apply it per-timeline with "
+                       "ApplyFairlightPresetToCurrentTimeline (exposed as "
+                       "resolve_control get_fairlight_presets + project_settings "
+                       "apply_fairlight_preset). Dial individual levels/pan/EQ/"
+                       "automation/FairlightFX in the Fairlight UI; beyond presets, "
+                       "only voice-isolation state and channel-mapping reads are "
+                       "scriptable.",
         "tags": ["missing-method", "audio", "fairlight"],
         "submit": "missing",
     },
+    {
+        "symbol": "AI Audio Assistant (one-click timeline auto-mix)",
+        "object": "Timeline / Project",
+        "reality": "The Fairlight AI Audio Assistant — which analyses a timeline "
+                   "and generates a balanced dialogue/music/effects mix — has no "
+                   "scripting method. Nothing matching it appears in the Resolve "
+                   "scripting API reference or in a dir() audit of Resolve, "
+                   "Project, Timeline or TimelineItem. Note this is NOT because it "
+                   "is a menu command: the API has no generic menu-invocation hook "
+                   "at all, so scriptability is per-feature, and plenty of menu "
+                   "commands DO have methods (DetectSceneCuts, Stabilize, "
+                   "SmartReframe, CreateMagicMask, TranscribeAudio, "
+                   "RemoveMotionBlur, AnalyzeForIntellisearch). It is compounded by "
+                   "the per-parameter Fairlight gap above: even the mix it produces "
+                   "cannot be read back or reconstructed clip-by-clip.",
+        "recommended": "No way to trigger it from a script. For a repeatable mix, "
+                       "run the Assistant once in the UI, save the result as a "
+                       "Fairlight preset, then apply that preset per-timeline with "
+                       "project_settings apply_fairlight_preset — content-adaptive "
+                       "per run is not achievable, a consistent template mix is.",
+        "tags": ["missing-method", "audio", "fairlight", "ai", "auto-mix"],
+        "submit": "missing",
+    },
     {
         "symbol": "Proxy / optimized-media generation",
         "object": "MediaPoolItem",
@@ -964,9 +1001,23 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "'subtitlePosition', 'subtitleAlignment', "
                    "'subtitlePreset', 'subtitleStyle'). Verified via dir(), "
                    "GetProperty(), and GetSetting() on Resolve 21.0.0.48.",
-        "recommended": "No workaround exists — subtitle styling is UI-only. "
-                       "Burn-in overlays via Fusion titles are a visual "
-                       "alternative but do not produce proper subtitle tracks.",
+        "recommended": "No API workaround exists, but the style IS reachable "
+                       "below the API: it lives in Sm2TiTrack.FieldsBlob for "
+                       "Type=2 tracks, as an EffectFiltersBA payload whose "
+                       "effect 136 carries a Qt QFont descriptor (param 18) and "
+                       "a normalised position vector (param 17). Exposed as "
+                       "project_db list_subtitle_styles / set_subtitle_style "
+                       "(font family/size/weight/italic + position). Confirmed "
+                       "live on Studio 19.1.3 (2026-08-06): Resolve opens a patched track "
+                       "and re-serialises it back to its own zstd form with the "
+                       "patched values intact, so it genuinely parses the write. "
+                       "Caveats: whole-TRACK style not per-caption, project must "
+                       "be CLOSED, Resolve must be fully quit and relaunched "
+                       "afterwards, and the track must already carry a style "
+                       "blob (a freshly added subtitle track has none until it "
+                       "is styled once in the UI). Burn-in overlays via Fusion "
+                       "titles remain a visual alternative but do not produce "
+                       "subtitle tracks.",
         "tags": ["missing-method", "subtitle", "style", "preset"],
         "submit": "missing",
     },
@@ -1373,6 +1424,60 @@ API_TRUTH: List[Dict[str, Any]] = [
         "issue": 59,
         "mitigation": ["_render_format_id", "_render_codec_id"],
     },
+    {
+        "symbol": "SetClipColor (undocumented value space; marker constants are a decoy)",
+        "object": "TimelineItem / MediaPoolItem",
+        "signature": "(colorName) -> bool",
+        "reality": "SetClipColor accepts exactly 16 names — the Edit-page clip-colour "
+                   "palette — and refuses everything else with a bare False, no "
+                   "exception and no other signal. Enumerated live on Studio "
+                   "19.1.3.7 (2026-08-06) against both objects; the accepted set is "
+                   "IDENTICAL on TimelineItem and MediaPoolItem: Orange, Apricot, "
+                   "Yellow, Lime, Olive, Green, Teal, Navy, Blue, Purple, Violet, "
+                   "Pink, Tan, Beige, Brown, Chocolate. The empty string is refused "
+                   "too. The trap is that the scripting reference documents "
+                   "colorName as a bare string with no enumerated values, while "
+                   "exporting the MARKER palette as constants (resolve.MARKER_ROSE, "
+                   "resolve.MARKER_FUCHSIA, ...) — so the only colour vocabulary "
+                   "reachable from the API surface is the wrong one. Cyan, Red, "
+                   "Fuchsia, Rose, Lavender, Sky, Mint, Lemon, Sand, Cocoa and Cream "
+                   "are all marker-only and all refused. Five names overlap both "
+                   "palettes (Blue, Green, Yellow, Pink, Purple), which is why the "
+                   "decoy survives: reasoning from the marker constants scores 5 of "
+                   "16 and looks like the right vocabulary with a few gaps.",
+        "recommended": "Pass only the 16 clip-colour names; on False, treat it as an "
+                       "invalid name rather than an item/lock/page problem. The set "
+                       "is pinned in utils/clip_colors.py and named in the refusal "
+                       "remediation, but deliberately NOT enforced — it was measured "
+                       "on one build and a later Resolve could extend it.",
+        "tags": ["timeline-item", "media-pool", "silent-failure", "undocumented-enum"],
+        "submit": "missing",
+        "issue": 124,
+        "mitigation": ["_set_clip_color_checked", "ti_set_clip_color"],
+    },
+    {
+        "symbol": "TimelineItem.SetClipColor on generator/title items",
+        "object": "TimelineItem",
+        "signature": "(colorName) -> bool",
+        "reality": "On a generator or title item SetClipColor returns True with a "
+                   "VALID colour name and the colour does not persist — GetClipColor "
+                   "still reads '' immediately afterwards, and ClearClipColor "
+                   "changes nothing because there is nothing to clear. Measured on "
+                   "Studio 19.1.3.7 (2026-08-06) on a Solid Color generator. A "
+                   "media-backed item on the SAME timeline in the same session "
+                   "persists correctly (SetClipColor('Teal') -> True, GetClipColor "
+                   "-> 'Teal'), so the bool is honest for some items and a lie for "
+                   "others, with nothing in the return value to tell them apart. A "
+                   "timeline item's colour is also independent of its backing "
+                   "MediaPoolItem's: colouring the item leaves the pool clip at ''.",
+        "recommended": "Never trust the bool alone — read GetClipColor back and "
+                       "compare. To mark a generator or title, use a timeline marker "
+                       "at its start instead; markers read back reliably.",
+        "tags": ["timeline-item", "silent-failure", "generator", "readback-lies"],
+        "submit": "bug",
+        "issue": 124,
+        "mitigation": ["_set_clip_color_checked", "ti_set_clip_color"],
+    },
     {
         "symbol": "Project.SetRenderSettings (inherits the loaded preset)",
         "object": "Project",

package/src/utils/clip_colors.py

@@ -0,0 +1,94 @@
+"""The value space of SetClipColor, and an honest refusal when a name misses.
+
+`SetClipColor(colorName) --> Bool` is documented with `colorName` as a bare
+string and no enumerated values anywhere in the scripting reference. The same
+reference *does* export a discoverable colour vocabulary — the marker constants
+(`resolve.MARKER_ROSE`, `resolve.MARKER_FUCHSIA`, …) — so the only colour names
+reachable from the API surface come from the marker palette, and those are
+largely the ones `SetClipColor` refuses. Issue #124 named this a decoy
+vocabulary, which is exactly right.
+
+Enumerated live on **DaVinci Resolve Studio 19.1.3.7 (macOS, 2026-08-06)**
+against both objects that expose the method. Both accept the same 16 names —
+the Edit-page clip-colour palette — and refuse everything else with a bare
+`False`, including every marker-only name and the empty string.
+
+The five names that overlap the two palettes (Blue, Green, Yellow, Pink,
+Purple) are what makes this trap so durable: an agent reasoning from the marker
+constants gets five hits out of sixteen and concludes the vocabulary is right.
+
+This set is deliberately NOT enforced. It was measured on one build, and a
+future Resolve could extend it; hard-rejecting an unlisted name would turn a
+working call into a failure on a build we have not seen. Callers pass the name
+through, and when Resolve refuses, the remediation names the measured-valid set.
+"""
+
+VERIFIED_ON = "DaVinci Resolve Studio 19.1.3.7 (macOS, 2026-08-06)"
+
+# Accepted by BOTH TimelineItem.SetClipColor and MediaPoolItem.SetClipColor.
+CLIP_COLORS = (
+    "Orange", "Apricot", "Yellow", "Lime", "Olive", "Green", "Teal", "Navy",
+    "Blue", "Purple", "Violet", "Pink", "Tan", "Beige", "Brown", "Chocolate",
+)
+
+# Measured refused. Kept explicit because these are the names an agent actually
+# reaches for: every one is either a marker constant or a common colour word.
+REFUSED_NAMES = (
+    "Cyan", "Red", "Fuchsia", "Rose", "Lavender", "Sky", "Mint", "Lemon",
+    "Sand", "Cocoa", "Cream", "Apple", "Magenta", "White", "Black", "Gray",
+    "Grey", "",
+)
+
+# The marker-palette names that are NOT clip colours — the decoy set proper.
+MARKER_ONLY_NAMES = (
+    "Cyan", "Red", "Fuchsia", "Rose", "Lavender", "Sky", "Mint", "Lemon",
+    "Sand", "Cocoa", "Cream",
+)
+
+
+def is_known_clip_color(color) -> bool:
+    """True if `color` is in the measured-valid set. Case-sensitive, as Resolve is."""
+    return isinstance(color, str) and color in CLIP_COLORS
+
+
+def clip_color_refusal(color) -> dict:
+    """Error payload for a SetClipColor that came back False.
+
+    Separates 'you used a marker name' from 'Resolve refused for another
+    reason', because the caller cannot tell them apart from the bare bool.
+    """
+    marker_decoy = isinstance(color, str) and color in MARKER_ONLY_NAMES
+    if marker_decoy:
+        reason = (
+            f"'{color}' is a MARKER colour, not a clip colour. The scripting "
+            "reference enumerates the marker constants and nothing else, so it "
+            "is the vocabulary an agent finds first — and SetClipColor refuses "
+            "most of it with a bare False."
+        )
+    elif is_known_clip_color(color):
+        reason = (
+            f"'{color}' is a valid clip colour on {VERIFIED_ON}, so this refusal "
+            "is about the item or the session, not the name. Note that "
+            "SetClipColor returns True WITHOUT persisting on generator and title "
+            "items — check GetClipColor rather than the bool."
+        )
+    else:
+        reason = (
+            f"'{color}' is not in the clip-colour palette. SetClipColor refuses "
+            "undocumented names with a bare False and no other signal."
+        )
+    return {
+        "reason": reason,
+        "remediation": (
+            "Use one of the 16 Edit-page clip colours: "
+            + ", ".join(CLIP_COLORS)
+            + f". Measured on {VERIFIED_ON}; the set is not enforced here because "
+            "a later build could extend it."
+        ),
+        "state": {
+            "requested_color": color,
+            "valid_colors": list(CLIP_COLORS),
+            "is_marker_only_name": marker_decoy,
+            "verified_on": VERIFIED_ON,
+        },
+    }