davinci-resolve-mcp 2.81.0 → 2.82.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 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.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 21 (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.0-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:** 26 missing capabilities, 29 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.
+- **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 21.0 (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

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.81.0"
+VERSION = "2.82.0"
 # 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.0",
   "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 21 (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.0"
 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.81.0"
+VERSION = "2.82.0"
 
 import base64
 import os

package/src/utils/api_truth.py

@@ -858,12 +858,46 @@ 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.",
+        "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 +998,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 21.0 (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",
     },