@mthines/reaper-mcp 0.19.0 → 0.70.2

package/reaper/mcp_extensions_lib.lua

@@ -0,0 +1,55 @@
+-- mcp_extensions_lib.lua — run a Lua command that an extension ships (extension_call).
+--
+-- An extension's handlers live in <bridge folder>/extensions/<name>/handlers.lua (the server copies the file
+-- there when it loads the extension) and return a table of command functions:
+--
+--   return { my_command = function(params, host) ... return data end }     -- or: return nil, "refusal"
+--
+-- `host` = { reaper, plan, fxstate, json_decode }. Extensions are trusted code the user installed; this lib
+-- only makes sure a command can name nothing outside its own file. Loaded by mcp_bridge.lua with dofile.
+
+local M = {}
+
+local cache = {} -- extension name -> { src, mod }: reloaded when the file's text changes
+
+function M.call(api, params, ctx)
+  local name, command = params.extension, params.command
+  if type(name) ~= "string" or not name:match("^[a-z][a-z0-9%-]+$") or #name > 32 then
+    return nil, "invalid extension name"
+  end
+  if type(command) ~= "string" or not command:match("^[%a_][%w_]*$") then
+    return nil, "invalid command name"
+  end
+
+  local path = ctx.dir .. name .. "/handlers.lua"
+  local src = ctx.read(path)
+  if not src then
+    return nil, "extension '" .. name .. "' has no Lua handlers installed; its manifest needs a \"lua\" file and the server must have loaded it"
+  end
+
+  local entry = cache[name]
+  if not entry or entry.src ~= src then
+    local chunk, cerr = load(src, "@" .. path, "t")
+    if not chunk then return nil, "extension '" .. name .. "': handlers.lua does not compile: " .. tostring(cerr) end
+    local ok, mod = pcall(chunk)
+    if not ok then return nil, "extension '" .. name .. "': handlers.lua failed to load: " .. tostring(mod) end
+    if type(mod) ~= "table" then return nil, "extension '" .. name .. "': handlers.lua must return a table of commands" end
+    entry = { src = src, mod = mod }
+    cache[name] = entry
+  end
+
+  local fn = entry.mod[command]
+  if type(fn) ~= "function" then return nil, "extension '" .. name .. "' has no Lua command '" .. command .. "'" end
+
+  local args = {}
+  if type(params.paramsJson) == "string" and params.paramsJson ~= "" then
+    local decoded, derr = ctx.plan.json_decode(params.paramsJson)
+    if derr then return nil, "paramsJson is not valid JSON: " .. tostring(derr) end
+    args = type(decoded) == "table" and decoded or {}
+  end
+
+  -- A crash inside the handler is the bridge's "Handler error:", a system fault: it is not caught here.
+  return fn(args, { reaper = api, plan = ctx.plan, fxstate = ctx.fxstate, json_decode = ctx.plan.json_decode })
+end
+
+return M

package/reaper/mcp_fxstate_lib.lua

@@ -0,0 +1,144 @@
+-- mcp_fxstate_lib.lua — read and replace one VST3 plugin's saved state in a track chunk.
+--
+-- Pure logic: every function takes the ReaScript API as `api` and `ctx` = { plan, dir, read, write }, so it
+-- runs under a fake API in unit tests. Loaded by mcp_bridge.lua with dofile.
+--
+-- The state is megabytes, so it never travels inside the command JSON: the caller names a file inside the
+-- bridge's data folder and this lib reads or writes it (line 1: base64 header, line 2: base64 state).
+--
+-- Why a new FXID on write: with the same FXID REAPER keeps the loaded instance and ignores the new state
+-- (verified on Vital, 2026-11-04). The VST3 length fields are the caller's job (libs/extension-api).
+
+local M = {}
+
+local WRAP = 280
+local FX_TAGS = { VST = true, JS = true, AU = true, CLAP = true, DX = true, VIDEO_EFFECT = true }
+
+local function split_lines(chunk)
+  local lines = {}
+  for line in (chunk .. "\n"):gmatch("(.-)\r?\n") do lines[#lines + 1] = line end
+  if lines[#lines] == "" then lines[#lines] = nil end
+  return lines
+end
+
+local function trim(s) return s:match("^%s*(.-)%s*$") end
+
+local function norm(path) return (tostring(path):gsub("\\", "/")) end
+
+--- A file this lib may touch: inside the bridge folder, named fxstate_<id>.in/.out, no "..".
+local function allowed_file(path, dir)
+  if type(path) ~= "string" or type(dir) ~= "string" then return false end
+  local p, d = norm(path), norm(dir)
+  if d:sub(-1) ~= "/" then d = d .. "/" end
+  if p:sub(1, #d) ~= d or p:find("..", 1, true) then return false end
+  return p:sub(#d + 1):match("^fxstate_[%w%-]+%.%a+$") ~= nil
+end
+
+--- The FX of a track chunk in chain order: { open, close, tag, header, name, fxid_line } (1-based line numbers).
+--- Returns list, lines, chain_end or nil, err.
+local function list_fx(chunk, plan)
+  local lines = split_lines(chunk)
+  local cs, ce = plan.find_block(lines, "FXCHAIN")
+  if not cs then return nil, "the track has no FX chain" end
+  local fx, current, d = {}, nil, 1
+  for i = cs + 1, ce - 1 do
+    local t = trim(lines[i])
+    if t:sub(1, 1) == "<" then
+      if d == 1 then
+        local tag = t:match("^<(%u[%u_%d]*)")
+        if tag == "CONTAINER" then
+          return nil, "FX containers are not supported yet (this track's chain has one)"
+        end
+        current = nil
+        if FX_TAGS[tag] then
+          current = { open = i, tag = tag, header = t, name = t:match('^<%u[%u_%d]*%s+"([^"]*)"') or "" }
+          fx[#fx + 1] = current
+        end
+      end
+      d = d + 1
+    elseif t == ">" then
+      d = d - 1
+      if d == 1 and current and not current.close then current.close = i end
+    elseif d == 1 and t:match("^FXID%s") and #fx > 0 and not fx[#fx].fxid_line then
+      fx[#fx].fxid_line = i
+    end
+  end
+  return fx, lines, ce
+end
+
+local function locate(api, params, ctx)
+  local track_ref = params.trackIndex
+  if track_ref == nil then return nil, "trackIndex is required" end
+  local fx_index = tonumber(params.fxIndex)
+  if not fx_index or fx_index < 0 or fx_index ~= math.floor(fx_index) then
+    return nil, "fxIndex must be a whole number, 0 or more"
+  end
+  local r, err = ctx.plan.resolve_track(api, track_ref, {})
+  if not r then return nil, err end
+  local ok, chunk = api.GetTrackStateChunk(r.track, "", false)
+  if not ok or not chunk or chunk == "" then return nil, "could not read the track's state" end
+  local fx, lines = list_fx(chunk, ctx.plan)
+  if not fx then return nil, lines end
+  local target = fx[fx_index + 1]
+  if not target then return nil, "FX " .. fx_index .. " not found (the track has " .. #fx .. " FX)" end
+  if target.tag ~= "VST" or not target.name:match("^VST3") then
+    return nil, "FX " .. fx_index .. " (" .. target.name .. ") is not a VST3 plugin; only VST3 state is supported"
+  end
+  if not target.close then return nil, "FX " .. fx_index .. " has an unreadable state block" end
+  return { track = r.track, fx = target, lines = lines, index = fx_index }
+end
+
+--- Read one VST3's state into params.outFile. Returns { name, format }.
+function M.get_fx_state(api, params, ctx)
+  if not allowed_file(params.outFile, ctx.dir) then return nil, "outFile must be an fxstate_* file in the bridge folder" end
+  local loc, err = locate(api, params, ctx)
+  if not loc then return nil, err end
+  local data = {}
+  for i = loc.fx.open + 1, loc.fx.close - 1 do
+    local t = trim(loc.lines[i])
+    if t ~= "" then data[#data + 1] = t end
+  end
+  if #data < 2 then return nil, "FX " .. loc.index .. " has no saved state to read" end
+  local ok, werr = ctx.write(params.outFile, data[1] .. "\n" .. table.concat(data, "", 2) .. "\n")
+  if not ok then return nil, "could not write " .. tostring(params.outFile) .. ": " .. tostring(werr) end
+  return { name = loc.fx.name, format = "vst3" }
+end
+
+--- Replace one VST3's state with the file params.inFile and give it a new FXID so REAPER reloads it.
+function M.set_fx_state(api, params, ctx)
+  if not allowed_file(params.inFile, ctx.dir) then return nil, "inFile must be an fxstate_* file in the bridge folder" end
+  local text = ctx.read(params.inFile)
+  if not text then return nil, "could not read " .. tostring(params.inFile) end
+  local header, state = text:match("^([^\n]+)\n([^\n]+)\n?")
+  local b64 = "^[A-Za-z0-9+/]+=?=?$"
+  if not header or not state or not header:match(b64) or not state:match(b64) then
+    return nil, "inFile must hold two base64 lines: the header, then the state"
+  end
+
+  local loc, err = locate(api, params, ctx)
+  if not loc then return nil, err end
+  if params.expectName and not loc.fx.name:find(tostring(params.expectName), 1, true) then
+    return nil, "FX " .. loc.index .. " is '" .. loc.fx.name .. "', not '" .. tostring(params.expectName) .. "'; nothing changed"
+  end
+  if not loc.fx.fxid_line then return nil, "FX " .. loc.index .. " has no FXID to renew; nothing changed" end
+
+  local out = {}
+  for i = 1, loc.fx.open do out[#out + 1] = loc.lines[i] end
+  out[#out + 1] = header
+  for at = 1, #state, WRAP do out[#out + 1] = state:sub(at, at + WRAP - 1) end
+  for i = loc.fx.close, #loc.lines do
+    if i == loc.fx.fxid_line then
+      out[#out + 1] = loc.lines[i]:match("^(%s*)") .. "FXID " .. api.genGuid("")
+    else
+      out[#out + 1] = loc.lines[i]
+    end
+  end
+
+  api.Undo_BeginBlock()
+  local ok = api.SetTrackStateChunk(loc.track, table.concat(out, "\n") .. "\n", false)
+  api.Undo_EndBlock("MCP: Set FX state (" .. loc.fx.name .. ")", -1)
+  if not ok then return nil, "REAPER refused the new track state" end
+  return { name = loc.fx.name, fxIndex = loc.index }
+end
+
+return M

package/reaper/mcp_gain_trace.jsfx

@@ -0,0 +1,126 @@
+desc:MCP Gain Trace (pre/post ducking meter)
+// Measures how much a chain of processors moves the level over time, live during playback.
+// Put one instance in mode "pre" at the start of a chain and one in mode "post" at the end (same slot).
+// Every 5 ms the post instance compares its 30 ms RMS with the pre RMS (post - pre, dB), at the
+// lag where they line up best (plugin latency in between), and reports percentiles relative to the
+// median gain: p5 / p1 = how deep the dips go, std = how much the gain moves.
+// Stats reset when playback starts or Reset changes. Audio passes through unmodified.
+// Everything runs in @sample. EEL2 has no scientific-notation literals (1e9 fails to compile).
+
+options:gmem=MCPGainTrace
+
+slider1:0<0,1,1{pre,post}>Mode
+slider2:0<0,7,1>Slot
+slider3:-45<-80,-20,1>Gate (dBFS, pre)
+slider4:0<-40,10,0.01>p5 (dB, rel. median)
+slider5:0<-40,10,0.01>p1 (dB, rel. median)
+slider6:0<0,20,0.01>Std (dB)
+slider7:0<-40,40,0.01>Median gain (dB)
+slider8:0<0,100000,0.1>Gated time (s)
+slider9:0<0,100,0.1>Lag (ms)
+slider10:0<0,1,1>Reset
+
+in_pin:left input
+in_pin:right input
+out_pin:left output
+out_pin:right output
+
+@init
+RING = 4096;      // windows kept per slot
+LAGS = 16;        // lags tried, in windows
+BINS = 600;       // histogram bins: -40..+20 dB, 0.1 dB
+BINLO = -40;
+hist = 0;         // LAGS * BINS
+sums = hist + LAGS * BINS; // per lag: n, sum, sumsq
+ph = sums + LAGS * 3;      // post window energies, ring of 64
+AVG = 6;                   // gain is compared over AVG windows (30 ms RMS), so waveform phase doesn't count
+win = floor(srate * 0.005);
+acc = 0; total = 0; seen = -1;
+was_playing = 0;
+last_reset = slider10;
+nwin = 0;
+
+function reset_stats() local(i) (
+  i = 0; loop(LAGS * BINS + LAGS * 3 + 64, hist[i] = 0; i += 1);
+  slider4 = slider5 = slider6 = slider7 = slider8 = slider9 = 0;
+);
+
+function update_stats() local(l, s, sd, best, bstd, n, h, c, b, q1, q5, q50) (
+  best = -1; bstd = 1000000000; l = 0;
+  loop(LAGS,
+    s = sums + l * 3;
+    s[0] > 20 ? (
+      sd = sqrt(max(0, s[2] / s[0] - sqr(s[1] / s[0])));
+      sd < bstd ? ( bstd = sd; best = l; );
+    );
+    l += 1;
+  );
+  best >= 0 ? (
+    s = sums + best * 3; n = s[0]; h = hist + best * BINS;
+    c = 0; b = 0; q1 = q5 = q50 = -1;
+    loop(BINS,
+      c += h[b];
+      q1 < 0 && c >= n * 0.01 ? q1 = b;
+      q5 < 0 && c >= n * 0.05 ? q5 = b;
+      q50 < 0 && c >= n * 0.5 ? q50 = b;
+      b += 1;
+    );
+    slider4 = (q5 - q50) / 10;
+    slider5 = (q1 - q50) / 10;
+    slider6 = bstd;
+    slider7 = BINLO + (q50 + 0.5) / 10;
+    slider8 = n * win / srate;
+    slider9 = best * win / srate * 1000;
+  );
+);
+
+reset_stats();
+
+@slider
+slider10 != last_reset ? ( last_reset = slider10; reset_stats(); );
+
+@sample
+base = 16 + slider2 * (RING + 16);
+playing = play_state & 1;
+slider1 == 1 && playing && !was_playing ? reset_stats();
+was_playing = playing;
+
+slider1 == 0 ? (
+  total += 1;
+  gmem[base - 16] = total;
+) : (
+  // pre ran its whole block before this one: when its count moves, this block starts at count - samplesblock
+  gmem[base - 16] != seen ? ( seen = gmem[base - 16]; total = seen - samplesblock; acc = 0; );
+  total += 1;
+);
+acc += spl0 * spl0 + spl1 * spl1;
+
+total % win == 0 ? (
+  k = total / win - 1;
+  e = acc / win;
+  slider1 == 0 ? (
+    gmem[base + (k % RING)] = e;
+  ) : playing ? (
+    ph[k % 64] = e;
+    E = 0; j = 0; loop(AVG, E += ph[(k - j + 64) % 64]; j += 1);
+    E /= AVG;
+    l = 0;
+    loop(LAGS,
+      kk = k - l;
+      p = 0; j = 0;
+      loop(AVG, p += (kk - j >= 0 ? gmem[base + ((kk - j) % RING)] : 0); j += 1);
+      p /= AVG;
+      p > 0 && E > 0 && 10 * log10(p) > slider3 ? (
+        g = 10 * log10(E / p);
+        b = min(BINS - 1, max(0, floor((g - BINLO) * 10)));
+        hist[l * BINS + b] += 1;
+        s = sums + l * 3;
+        s[0] += 1; s[1] += g; s[2] += g * g;
+      );
+      l += 1;
+    );
+    nwin += 1;
+    nwin % 100 == 0 ? update_stats();
+  );
+  acc = 0;
+);