@mthines/reaper-mcp 0.19.0 → 0.70.2

package/reaper/mcp_lufs_meter.jsfx

@@ -4,7 +4,7 @@ desc:MCP LUFS Meter
 // Writes results to shared memory (gmem) so the Lua bridge can read them.
 //
 // gmem layout (per track slot, 8 slots each):
-//   base = track_slot * 8
+//   base = track_slot * 8   (the bridge sets track_slot = trackIndex + 1, master = 0)
 //   gmem[base+0] = integrated LUFS (running average since last reset)
 //   gmem[base+1] = short-term LUFS (3-second sliding window)
 //   gmem[base+2] = momentary LUFS (400ms sliding window)
@@ -15,7 +15,7 @@ desc:MCP LUFS Meter
 options:gmem=MCPLufsMeter
 
 slider1:reset_btn=0<0,1,1{Idle,Reset}>Reset Measurement
-slider2:track_slot=0<0,127,1>Track Slot
+slider2:track_slot=0<0,4095,1>Track Slot
 
 @init
   // K-weighting filter state (two biquad stages per channel)
@@ -33,8 +33,9 @@ slider2:track_slot=0<0,127,1>Track Slot
   // Ring buffer for per-sample squared weighted values (up to 3s)
   // momentary: 400ms window, short-term: 3s window
   buf_size = 0;
-  buf_l = 65536;          // start address for left channel ring buffer
-  buf_r = 131072;         // start address for right channel ring buffer
+  // Each buffer holds up to 262144 samples (+2 for the true-peak history)
+  buf_l = 0;              // start address for left channel ring buffer
+  buf_r = 270000;         // start address for right channel ring buffer
   buf_pos = 0;
 
   // Running sums for windows
@@ -79,7 +80,7 @@ slider2:track_slot=0<0,127,1>Track Slot
   );
 
   function reset_measurement() (
-    base = floor(slider2 + 0.5) * 8;
+    base = floor(track_slot + 0.5) * 8;
     buf_pos = 0;
     momentary_sum_l = 0;
     momentary_sum_r = 0;
@@ -110,10 +111,11 @@ slider2:track_slot=0<0,127,1>Track Slot
   needs_init = 1;
 
   // Handle reset button
-  slider1 == 1 ? (
+  // Named sliders live in their variables; slider1/slider2 stay 0
+  reset_btn == 1 ? (
     reset_measurement();
-    slider1 = 0;
-    sliderchange(slider1);
+    reset_btn = 0;
+    sliderchange(1);  // mask: slider1
   );
 
 @sample
@@ -211,17 +213,18 @@ slider2:track_slot=0<0,127,1>Track Slot
 
   // --- Update gmem every 4096 samples (approx 10x/second at 44.1kHz) ---
   (sample_count % 4096) == 0 ? (
-    base = floor(slider2 + 0.5) * 8;
+    base = floor(track_slot + 0.5) * 8;
 
     mom_samples = floor(srate * 0.4);
     mom_samples < 1 ? mom_samples = 1;
 
     // Mean square over each window
-    shortterm_mean = (shortterm_sum_l + shortterm_sum_r) / (buf_size * 2);
-    momentary_mean = (momentary_sum_l + momentary_sum_r) / (mom_samples * 2);
+    // BS.1770 sums the channels' mean squares (G = 1 for L/R); it does not average them
+    shortterm_mean = (shortterm_sum_l + shortterm_sum_r) / buf_size;
+    momentary_mean = (momentary_sum_l + momentary_sum_r) / mom_samples;
 
-    // Integrated mean square (two channels)
-    integrated_mean = integrated_count > 0 ? (integrated_sum / (integrated_count * 2)) : 0;
+    // Integrated: sum of the two channels' mean squares
+    integrated_mean = integrated_count > 0 ? (integrated_sum / integrated_count) : 0;
 
     // LUFS = -0.691 + 10 * log10(mean_square)
     shortterm_mean > 0 ? (

package/reaper/mcp_midi_lib.lua

@@ -0,0 +1,555 @@
+-- mcp_midi_lib.lua — MIDI composition edits: quantize, transform (transpose, velocity,
+-- humanize, lengths), import of parsed MIDI file data, the pitch-class profile detect_key
+-- reads, and the bar/beat grid with per-segment profiles detect_chords reads.
+-- Pure logic over an injected ReaScript API, unit-tested via wasmoon against a fake.
+-- Loaded by mcp_bridge.lua.
+-- Every function checks all of its input before the first write, so a refused request
+-- changes nothing; each write is one undo point. Times are quarter notes (beats) on the
+-- project grid: quantize snaps to the project's beats, not the item's start.
+
+local M = {}
+
+M.MAX_IMPORT_NOTES = 20000
+M.MAX_IMPORT_TRACKS = 32
+M.MAX_PROFILE_ITEMS = 256
+
+local EPS = 1e-9
+
+local function num(v) return type(v) == "number" and v == v and v ~= math.huge and v ~= -math.huge end
+local function int(v) return num(v) and v == math.floor(v) end
+local function r4(x) return math.floor(x * 10000 + 0.5) / 10000 end
+
+local function with_undo(api, label, fn)
+  api.Undo_BeginBlock()
+  local ok, res, err = pcall(fn)
+  if ok then
+    api.Undo_EndBlock(label, -1)
+    api.UpdateArrange()
+    return res, err
+  end
+  -- A failure half way (an import that made some tracks) leaves no partial edit. The failed
+  -- block gets its own label, so a failure that wrote nothing (no undo point) never undoes
+  -- the user's last edit, even one by this same tool
+  local revert = label .. " (failed — reverting)"
+  api.Undo_EndBlock(revert, -1)
+  local undone = api.Undo_CanUndo2 and api.Undo_CanUndo2(0) == revert
+  if undone then api.Undo_DoUndo2(0) end
+  api.UpdateArrange()
+  return nil, "Handler error: " .. tostring(res) .. (undone and " — the edit was undone" or "")
+end
+
+-- The MIDI take of a track/item pair, or why not
+local function midi_take(api, p)
+  if not int(p.trackIndex) or p.trackIndex < 0 then return nil, "trackIndex must be 0 or more" end
+  if not int(p.itemIndex) or p.itemIndex < 0 then return nil, "itemIndex must be 0 or more" end
+  local tr = api.GetTrack(0, p.trackIndex)
+  if not tr then return nil, "track " .. p.trackIndex .. " not found" end
+  local n = api.CountTrackMediaItems(tr)
+  if p.itemIndex >= n then return nil, "item " .. p.itemIndex .. " not found (track has " .. n .. " items)" end
+  local item = api.GetTrackMediaItem(tr, p.itemIndex)
+  local take = item and api.GetActiveTake(item)
+  if not take then return nil, "the item has no active take" end
+  if not api.TakeIsMIDI(take) then return nil, "item " .. p.itemIndex .. " is not a MIDI item" end
+  return { track = tr, item = item, take = take, startQN = api.TimeMap2_timeToQN(0, api.GetMediaItemInfo_Value(item, "D_POSITION")) }
+end
+
+-- Every note of a take as { i, sel, muted, s, e, qs, qe, chan, pitch, vel } (q* = project quarter notes)
+local function read_notes(api, t)
+  local _, count = api.MIDI_CountEvts(t.take)
+  local notes = {}
+  for i = 0, count - 1 do
+    local _, sel, muted, s, e, chan, pitch, vel = api.MIDI_GetNote(t.take, i)
+    notes[#notes + 1] = { i = i, sel = sel, muted = muted, s = s, e = e, chan = chan, pitch = pitch, vel = vel,
+      qs = api.MIDI_GetProjQNFromPPQPos(t.take, s), qe = api.MIDI_GetProjQNFromPPQPos(t.take, e) }
+  end
+  return notes
+end
+
+-- The notes a call acts on: given indexes, else a pitch range and/or channel, else all
+local function pick(notes, p)
+  if p.notes ~= nil then
+    if type(p.notes) ~= "table" or #p.notes == 0 then return nil, "notes must be a list of note indexes" end
+    local out, seen = {}, {}
+    for _, i in ipairs(p.notes) do
+      if not int(i) or i < 0 or i >= #notes then return nil, "note " .. tostring(i) .. " not found (the item has " .. #notes .. " notes)" end
+      if not seen[i] then seen[i] = true; out[#out + 1] = notes[i + 1] end
+    end
+    return out
+  end
+  local lo, hi = p.pitchMin or 0, p.pitchMax or 127
+  if not int(lo) or not int(hi) or lo < 0 or hi > 127 or lo > hi then return nil, "pitchMin/pitchMax must be 0-127, min ≤ max" end
+  if p.channel ~= nil and (not int(p.channel) or p.channel < 0 or p.channel > 15) then return nil, "channel must be 0-15" end
+  local out = {}
+  for _, n in ipairs(notes) do
+    if n.pitch >= lo and n.pitch <= hi and (p.channel == nil or n.chan == p.channel) then out[#out + 1] = n end
+  end
+  if #out == 0 then return nil, "no notes match" end
+  return out
+end
+
+local function write_notes(api, t, changed)
+  local ok, err = pcall(function()
+    for _, n in ipairs(changed) do
+      api.MIDI_SetNote(t.take, n.i, nil, nil, api.MIDI_GetPPQPosFromProjQN(t.take, n.nqs),
+        api.MIDI_GetPPQPosFromProjQN(t.take, n.nqe), nil, n.npitch, n.nvel, true)
+    end
+  end)
+  api.MIDI_Sort(t.take)
+  -- MIDI API edits leave the item unmarked; without this REAPER folds the edit into the previous
+  -- MIDI undo point and undo restores a mixed state (seen in REAPER 7.40). Marked even when a
+  -- write failed half way, so the failed block has an undo point for with_undo to revert
+  api.MarkTrackItemsDirty(t.track, t.item)
+  if not ok then error(err, 0) end
+end
+
+-- -----------------------------------------------------------------------------
+-- Quantize
+-- -----------------------------------------------------------------------------
+
+-- The grid line nearest qn, with every second line pushed later by `swing` of a grid step
+local function snap(qn, grid, swing)
+  local k = math.floor(qn / grid + 0.5)
+  local best, best_d
+  for j = k - 1, k + 1 do
+    local line = j * grid + ((j % 2 == 1) and swing * grid or 0)
+    local d = math.abs(qn - line)
+    if not best_d or d < best_d then best, best_d = line, d end
+  end
+  return best
+end
+
+-- The grid line after a line (with swing, odd lines sit swing steps late)
+local function line_after(line, grid, swing)
+  local j = math.floor((line + EPS) / grid) + 1
+  return j * grid + ((j % 2 == 1) and swing * grid or 0)
+end
+
+local function check_quantize(api, p)
+  local t, err = midi_take(api, p)
+  if not t then return nil, err end
+  if not num(p.grid) or p.grid <= 0 or p.grid > 16 then return nil, "grid must be more than 0 and at most 16 beats (0.25 = 16ths)" end
+  local strength = p.strength == nil and 1 or p.strength
+  if not num(strength) or strength < 0 or strength > 1 then return nil, "strength must be 0-1" end
+  local swing = p.swing or 0
+  if not num(swing) or swing < 0 or swing > 0.9 then return nil, "swing must be 0-0.9" end
+  local window = p.window == nil and 1 or p.window
+  if not num(window) or window <= 0 or window > 1 then return nil, "window must be more than 0 and at most 1" end
+  local lengths = p.lengths or "keep"
+  if lengths ~= "keep" and lengths ~= "quantize" then return nil, "lengths must be keep or quantize" end
+  local picked, perr = pick(read_notes(api, t), p)
+  if not picked then return nil, perr end
+  return { t = t, notes = picked, grid = p.grid, strength = strength, swing = swing, window = window, lengths = lengths }
+end
+
+local function apply_quantize(api, c)
+  local changed, shifts, max_shift = {}, 0, 0
+  -- With swing the lines are up to (1 + swing) steps apart, so window 1 still reaches every note
+  local reach = c.window * (1 + c.swing) * c.grid / 2 + EPS
+  for _, n in ipairs(c.notes) do
+    local line = snap(n.qs, c.grid, c.swing)
+    -- Never before the item start, where REAPER would not play the note
+    while line < c.t.startQN - EPS do line = line_after(line, c.grid, c.swing) end
+    local off = line - n.qs
+    -- Notes further from a line than the window are left where they are
+    if math.abs(off) <= reach then
+      -- Blend, so a full-strength note lands exactly on the line
+      n.nqs = line * c.strength + n.qs * (1 - c.strength)
+      if c.lengths == "quantize" then
+        local e = snap(n.qe, c.grid, c.swing)
+        if e <= line + EPS then e = line_after(line, c.grid, c.swing) end
+        n.nqe = e * c.strength + n.qe * (1 - c.strength)
+      else
+        n.nqe = n.qe + (n.nqs - n.qs)
+      end
+      -- A note already on the grid still counts when its end snapped
+      if math.abs(n.nqs - n.qs) > EPS or math.abs(n.nqe - n.qe) > EPS then
+        changed[#changed + 1] = n
+        shifts = shifts + math.abs(off)
+        if math.abs(off) > max_shift then max_shift = math.abs(off) end
+      end
+    end
+  end
+  write_notes(api, c.t, changed)
+  return { notes = #c.notes, moved = #changed, grid = c.grid, strength = c.strength, swing = c.swing,
+    avgShiftBeats = #changed > 0 and r4(shifts / #changed) or 0, maxShiftBeats = r4(max_shift) }
+end
+
+function M.quantize(api, p)
+  local c, err = check_quantize(api, p)
+  if not c then return nil, err .. " — nothing changed" end
+  return with_undo(api, "MCP: Quantize MIDI", function() return apply_quantize(api, c) end)
+end
+
+-- -----------------------------------------------------------------------------
+-- Transform: transpose, velocity, humanize, lengths
+-- -----------------------------------------------------------------------------
+
+-- Reproducible pseudo-random numbers in -1..1 (a seed gives the same humanize every time)
+local function rng(seed)
+  local state = (math.floor(seed) % 2147483646) + 1
+  return function()
+    state = (state * 16807) % 2147483647
+    return (state / 2147483647) * 2 - 1
+  end
+end
+
+local function check_transform(api, p)
+  local t, err = midi_take(api, p)
+  if not t then return nil, err end
+  local c = { t = t }
+  if p.transpose ~= nil and (not int(p.transpose) or p.transpose < -48 or p.transpose > 48) then return nil, "transpose must be a whole number of semitones, -48 to 48" end
+  local v = p.velocity or {}
+  if type(v) ~= "table" then return nil, "velocity must be an object" end
+  if v.set ~= nil and (not int(v.set) or v.set < 1 or v.set > 127) then return nil, "velocity.set must be 1-127" end
+  if v.scale ~= nil and (not num(v.scale) or v.scale < 0 or v.scale > 4) then return nil, "velocity.scale must be 0-4" end
+  if v.add ~= nil and (not int(v.add) or v.add < -126 or v.add > 126) then return nil, "velocity.add must be -126 to 126" end
+  local vmin, vmax = v.min or 1, v.max or 127
+  if not int(vmin) or not int(vmax) or vmin < 1 or vmax > 127 or vmin > vmax then return nil, "velocity.min/max must be 1-127, min ≤ max" end
+  local h = p.humanize or {}
+  if type(h) ~= "table" then return nil, "humanize must be an object" end
+  if h.timingBeats ~= nil and (not num(h.timingBeats) or h.timingBeats < 0 or h.timingBeats > 0.25) then return nil, "humanize.timingBeats must be 0-0.25" end
+  if h.velocity ~= nil and (not int(h.velocity) or h.velocity < 0 or h.velocity > 64) then return nil, "humanize.velocity must be 0-64" end
+  if h.seed ~= nil and not int(h.seed) then return nil, "humanize.seed must be a whole number" end
+  local l = p.length or {}
+  if type(l) ~= "table" then return nil, "length must be an object" end
+  if l.set ~= nil and (not num(l.set) or l.set <= 0 or l.set > 64) then return nil, "length.set must be more than 0 and at most 64 beats" end
+  if l.scale ~= nil and (not num(l.scale) or l.scale <= 0 or l.scale > 8) then return nil, "length.scale must be more than 0 and at most 8" end
+  if l.legato ~= nil and type(l.legato) ~= "boolean" then return nil, "length.legato must be true or false" end
+  if p.transpose == nil and next(v) == nil and next(h) == nil and next(l) == nil then
+    return nil, "give at least one of transpose, velocity, humanize or length"
+  end
+  local all = read_notes(api, t)
+  local picked, perr = pick(all, p)
+  if not picked then return nil, perr end
+  if p.transpose then
+    local out = 0
+    for _, n in ipairs(picked) do
+      local np = n.pitch + p.transpose
+      if np < 0 or np > 127 then out = out + 1 end
+    end
+    if out > 0 then return nil, out .. " note(s) would leave the MIDI range 0-127 when transposed by " .. p.transpose end
+  end
+  c.all, c.notes, c.transpose, c.v, c.vmin, c.vmax, c.h, c.l = all, picked, p.transpose or 0, v, vmin, vmax, h, l
+  return c
+end
+
+local function apply_transform(api, c)
+  local rand = rng(c.h.seed or 1)
+  local v, h, l = c.v, c.h, c.l
+  local clamped, vel_before, vel_after = 0, 0, 0
+  -- Starts first (humanize moves them), so legato ends meet the notes where they end up
+  for _, n in ipairs(c.notes) do
+    n.nqs = n.qs
+    if h.timingBeats and h.timingBeats > 0 then n.nqs = math.max(c.t.startQN, n.qs + rand() * h.timingBeats) end
+  end
+  -- Legato: each note runs to the next picked note's start on the same channel
+  local next_start = {}
+  if l.legato then
+    local order = {}
+    for _, n in ipairs(c.notes) do order[#order + 1] = n end
+    table.sort(order, function(a, b) return a.nqs < b.nqs end)
+    for k, n in ipairs(order) do
+      for j = k + 1, #order do
+        if order[j].chan == n.chan and order[j].nqs > n.nqs + EPS then next_start[n] = order[j].nqs; break end
+      end
+    end
+  end
+  for _, n in ipairs(c.notes) do
+    n.npitch = n.pitch + c.transpose
+    local vel = n.vel
+    if v.set then vel = v.set end
+    if v.scale then vel = vel * v.scale end
+    if v.add then vel = vel + v.add end
+    if h.velocity and h.velocity > 0 then vel = vel + rand() * h.velocity end
+    vel = math.floor(vel + 0.5)
+    local cl = math.max(c.vmin, math.min(c.vmax, vel))
+    if cl ~= vel then clamped = clamped + 1 end
+    n.nvel = cl
+    vel_before, vel_after = vel_before + n.vel, vel_after + cl
+    local len = n.qe - n.qs
+    if l.set then len = l.set end
+    if l.scale then len = len * l.scale end
+    if l.legato and next_start[n] then len = next_start[n] - n.nqs end
+    n.nqe = n.nqs + math.max(len, 1 / 960)
+  end
+  write_notes(api, c.t, c.notes)
+  local n = #c.notes
+  return { notes = n, transpose = c.transpose, velocityClamped = clamped,
+    avgVelocityBefore = r4(vel_before / n), avgVelocityAfter = r4(vel_after / n),
+    seed = (h.timingBeats or h.velocity) and (h.seed or 1) or nil }
+end
+
+function M.transform(api, p)
+  local c, err = check_transform(api, p)
+  if not c then return nil, err .. " — nothing changed" end
+  return with_undo(api, "MCP: Transform MIDI", function() return apply_transform(api, c) end)
+end
+
+-- -----------------------------------------------------------------------------
+-- Import parsed MIDI file data
+-- -----------------------------------------------------------------------------
+
+-- p.tracks: [{ name, notes = {{startQN, lenQN, chan, pitch, vel}, ...}, cc = {{qn, chan, cc, value}, ...} }]
+local function check_import(api, p)
+  if not num(p.position) or p.position < 0 then return nil, "position must be 0 or more seconds" end
+  if type(p.tracks) ~= "table" or #p.tracks == 0 then return nil, "the file holds no notes or controllers" end
+  if p.newTracks and #p.tracks > M.MAX_IMPORT_TRACKS then return nil, "the file has " .. #p.tracks .. " tracks with notes; at most " .. M.MAX_IMPORT_TRACKS end
+  if not num(p.lengthQN) or p.lengthQN <= 0 then return nil, "lengthQN must be more than 0" end
+  local n_tracks = api.CountTracks(0)
+  if not int(p.trackIndex) or p.trackIndex < 0 then return nil, "trackIndex must be 0 or more" end
+  if p.newTracks then
+    if p.trackIndex > n_tracks then return nil, "trackIndex " .. p.trackIndex .. " is past the last track (" .. n_tracks .. " tracks)" end
+  elseif p.trackIndex >= n_tracks then
+    return nil, "track " .. p.trackIndex .. " not found"
+  end
+  local total = 0
+  for k, t in ipairs(p.tracks) do
+    if type(t.notes) ~= "table" or type(t.cc or {}) ~= "table" then return nil, "track " .. k .. " is malformed" end
+    total = total + #t.notes
+    for _, n in ipairs(t.notes) do
+      if not (num(n[1]) and n[1] >= 0 and num(n[2]) and n[2] > 0 and int(n[3]) and n[3] >= 0 and n[3] <= 15
+        and int(n[4]) and n[4] >= 0 and n[4] <= 127 and int(n[5]) and n[5] >= 1 and n[5] <= 127) then
+        return nil, "track " .. k .. " has a malformed note"
+      end
+    end
+    for _, e in ipairs(t.cc or {}) do
+      if not (num(e[1]) and e[1] >= 0 and int(e[2]) and e[2] >= 0 and e[2] <= 15 and int(e[3]) and e[3] >= 0
+        and e[3] <= 127 and int(e[4]) and e[4] >= 0 and e[4] <= 127) then
+        return nil, "track " .. k .. " has a malformed controller event"
+      end
+    end
+  end
+  if total > M.MAX_IMPORT_NOTES then return nil, "the file has " .. total .. " notes; at most " .. M.MAX_IMPORT_NOTES .. " per import" end
+  return p
+end
+
+local function apply_import(api, p)
+  local startQN = api.TimeMap2_timeToQN(0, p.position)
+  local endQN = startQN + p.lengthQN
+  local groups = p.tracks
+  if not p.newTracks and #groups > 1 then
+    -- One item: every file track's notes merged
+    local merged = { name = p.name or groups[1].name, notes = {}, cc = {} }
+    for _, t in ipairs(groups) do
+      for _, n in ipairs(t.notes) do merged.notes[#merged.notes + 1] = n end
+      for _, e in ipairs(t.cc or {}) do merged.cc[#merged.cc + 1] = e end
+    end
+    groups = { merged }
+  end
+  local items = {}
+  for k, g in ipairs(groups) do
+    local idx = p.trackIndex
+    if p.newTracks then
+      idx = p.trackIndex + k - 1
+      api.InsertTrackAtIndex(idx, true)
+      if g.name and g.name ~= "" then api.GetSetMediaTrackInfo_String(api.GetTrack(0, idx), "P_NAME", g.name, true) end
+    end
+    local tr = api.GetTrack(0, idx)
+    local item = api.CreateNewMIDIItemInProj(tr, startQN, endQN, true)
+    local take = api.GetActiveTake(item)
+    if g.name and g.name ~= "" then api.GetSetMediaItemTakeInfo_String(take, "P_NAME", g.name, true) end
+    for _, n in ipairs(g.notes) do
+      api.MIDI_InsertNote(take, false, false, api.MIDI_GetPPQPosFromProjQN(take, startQN + n[1]),
+        api.MIDI_GetPPQPosFromProjQN(take, startQN + n[1] + n[2]), n[3], n[4], n[5], true)
+    end
+    for _, e in ipairs(g.cc or {}) do
+      api.MIDI_InsertCC(take, false, false, api.MIDI_GetPPQPosFromProjQN(take, startQN + e[1]), 0xB0, e[2], e[3], e[4])
+    end
+    api.MIDI_Sort(take)
+    api.MarkTrackItemsDirty(tr, item)
+    local itemIndex
+    for i = 0, api.CountTrackMediaItems(tr) - 1 do
+      if api.GetTrackMediaItem(tr, i) == item then itemIndex = i end
+    end
+    items[#items + 1] = { trackIndex = idx, itemIndex = itemIndex, name = g.name or "", notes = #g.notes, cc = #(g.cc or {}) }
+  end
+  return { position = p.position, lengthBeats = r4(p.lengthQN), items = items }
+end
+
+function M.import(api, p)
+  local c, err = check_import(api, p)
+  if not c then return nil, err .. " — nothing changed" end
+  return with_undo(api, "MCP: Import MIDI file", function() return apply_import(api, c) end)
+end
+
+-- -----------------------------------------------------------------------------
+-- Pitch-class profile (for detect_key)
+-- -----------------------------------------------------------------------------
+
+-- Every heard note of a track's MIDI items overlapping [t0, t1) as { qs, qe, pitch, w } in project
+-- quarter notes, clipped to the range and the item edges; w = velocity / 127. Unmuted notes of
+-- unmuted items only, drums (GM channel 10) skipped. Also the item counts.
+local function heard_notes(api, tr, t0, t1)
+  local q0 = api.TimeMap2_timeToQN(0, t0)
+  local q1 = t1 and api.TimeMap2_timeToQN(0, t1) or math.huge
+  local out = {}
+  local counts = { notes = 0, midiItems = 0, audioItems = 0, capped = 0 }
+  -- The cap counts only items that overlap the range, so a late range on a long track is still read
+  local read = 0
+  for i = 0, api.CountTrackMediaItems(tr) - 1 do
+    local item = api.GetTrackMediaItem(tr, i)
+    local take = api.GetActiveTake(item)
+    local ipos = api.GetMediaItemInfo_Value(item, "D_POSITION")
+    local overlaps = ipos < (t1 or math.huge) and ipos + api.GetMediaItemInfo_Value(item, "D_LENGTH") > t0
+    if overlaps and read >= M.MAX_PROFILE_ITEMS then counts.capped = counts.capped + 1; overlaps = false end
+    if overlaps then read = read + 1 end
+    if overlaps and take and api.GetMediaItemInfo_Value(item, "B_MUTE") == 0 then
+      if api.TakeIsMIDI(take) then
+        counts.midiItems = counts.midiItems + 1
+        -- Only what the item shows: notes past a trimmed edge are not heard (a loop's repeats count once)
+        local i0 = math.max(q0, api.TimeMap2_timeToQN(0, ipos))
+        local i1 = math.min(q1, api.TimeMap2_timeToQN(0, ipos + api.GetMediaItemInfo_Value(item, "D_LENGTH")))
+        local _, count = api.MIDI_CountEvts(take)
+        for n = 0, count - 1 do
+          local _, _, muted, s, e, chan, pitch, vel = api.MIDI_GetNote(take, n)
+          local qs = math.max(api.MIDI_GetProjQNFromPPQPos(take, s), i0)
+          local qe = math.min(api.MIDI_GetProjQNFromPPQPos(take, e), i1)
+          -- Drums (GM channel 10) carry no key
+          if not muted and chan ~= 9 and qe > qs then
+            out[#out + 1] = { qs = qs, qe = qe, pitch = pitch, w = vel / 127 }
+            counts.notes = counts.notes + 1
+          end
+        end
+      else
+        counts.audioItems = counts.audioItems + 1
+      end
+    end
+  end
+  return out, counts
+end
+
+-- Note time per pitch class (C = 1 … B = 12) over a track's MIDI items in [start, end),
+-- weighted by duration and velocity. Unmuted notes of unmuted items only.
+function M.pitch_profile(api, p)
+  if not int(p.trackIndex) or p.trackIndex < 0 then return nil, "trackIndex must be 0 or more" end
+  local tr = api.GetTrack(0, p.trackIndex)
+  if not tr then return nil, "track " .. p.trackIndex .. " not found" end
+  local t0, t1 = p.startTime or 0, p.endTime
+  if not num(t0) or t0 < 0 then return nil, "startTime must be 0 or more" end
+  if t1 ~= nil and (not num(t1) or t1 <= t0) then return nil, "endTime must be after startTime" end
+  local notes, c = heard_notes(api, tr, t0, t1)
+  local chroma = {}
+  for k = 1, 12 do chroma[k] = 0 end
+  for _, n in ipairs(notes) do chroma[n.pitch % 12 + 1] = chroma[n.pitch % 12 + 1] + (n.qe - n.qs) * n.w end
+  for k = 1, 12 do chroma[k] = r4(chroma[k]) end
+  local out = { chroma = chroma, notes = c.notes, midiItems = c.midiItems, audioItems = c.audioItems }
+  if c.capped > 0 then out.itemsNotRead = c.capped end
+  return out
+end
+
+M.MAX_CHORD_SEGMENTS = 4000
+
+-- The range detect_chords / detect_key read: an item's bounds (itemIndex), else startTime to endTime,
+-- where a missing end is where the track's last item ends (the project's length on the master)
+local function chord_range(api, p)
+  if not int(p.trackIndex) or p.trackIndex < -1 then return nil, "trackIndex must be -1 (master) or more" end
+  local tr = p.trackIndex == -1 and api.GetMasterTrack(0) or api.GetTrack(0, p.trackIndex)
+  if not tr then return nil, "track " .. p.trackIndex .. " not found" end
+  if p.itemIndex ~= nil then
+    if p.trackIndex < 0 then return nil, "the master track holds no items: give a track index with itemIndex" end
+    if not int(p.itemIndex) or p.itemIndex < 0 then return nil, "itemIndex must be 0 or more" end
+    local n = api.CountTrackMediaItems(tr)
+    if p.itemIndex >= n then return nil, "item " .. p.itemIndex .. " not found (track has " .. n .. " items)" end
+    local item = api.GetTrackMediaItem(tr, p.itemIndex)
+    local pos = api.GetMediaItemInfo_Value(item, "D_POSITION")
+    return tr, pos, pos + api.GetMediaItemInfo_Value(item, "D_LENGTH")
+  end
+  local t0, t1 = p.startTime or 0, p.endTime
+  if not num(t0) or t0 < 0 then return nil, "startTime must be 0 or more" end
+  if t1 == nil then
+    if p.trackIndex == -1 then
+      t1 = api.GetProjectLength(0)
+    else
+      t1 = 0
+      for i = 0, api.CountTrackMediaItems(tr) - 1 do
+        local item = api.GetTrackMediaItem(tr, i)
+        t1 = math.max(t1, api.GetMediaItemInfo_Value(item, "D_POSITION") + api.GetMediaItemInfo_Value(item, "D_LENGTH"))
+      end
+    end
+    if t1 <= t0 then return nil, "nothing to read: the track has no items after " .. t0 .. " s" end
+  elseif not num(t1) or t1 <= t0 then
+    return nil, "endTime must be after startTime"
+  end
+  return tr, t0, t1
+end
+
+-- The range an item covers, for detect_key's itemIndex
+function M.item_range(api, p)
+  local tr, t0, t1 = chord_range(api, p)
+  if not tr then return nil, t0 end
+  return { startTime = t0, endTime = t1 }
+end
+
+-- Segments of [t0, t1) on the project grid, one per bar or beat (tempo and time signature
+-- changes followed), each { start, end, bar, beat } with 1-based bar and beat; the first and
+-- last are clipped to the range
+local function grid_segments(api, t0, t1, per)
+  local segs = {}
+  local _, m = api.TimeMap2_timeToBeats(0, t0)
+  m = math.floor(m)
+  while true do
+    local _, qs, qe, numer, denom = api.TimeMap_GetMeasureInfo(0, m)
+    local step = per == "beat" and 4 / denom or (qe - qs)
+    local beats = per == "beat" and numer or 1
+    for k = 0, beats - 1 do
+      local a = api.TimeMap2_QNToTime(0, qs + k * step)
+      local b = api.TimeMap2_QNToTime(0, k == beats - 1 and qe or qs + (k + 1) * step)
+      if a >= t1 - EPS then return segs end
+      a, b = math.max(a, t0), math.min(b, t1)
+      if b - a > 1e-6 then
+        if #segs >= M.MAX_CHORD_SEGMENTS then return nil end
+        segs[#segs + 1] = { start = r4(a), ["end"] = r4(b), bar = m + 1, beat = k + 1, q0 = api.TimeMap2_timeToQN(0, a), q1 = api.TimeMap2_timeToQN(0, b) }
+      end
+    end
+    m = m + 1
+  end
+end
+
+-- detect_chords: the range (item bounds or start/end), one segment per bar or beat, and with
+-- midi = true each segment's pitch-class profile (note time x velocity) and lowest held note
+function M.chord_grid(api, p)
+  local tr, t0, t1 = chord_range(api, p)
+  if not tr then return nil, t0 end
+  local per = p.per or "bar"
+  if per ~= "bar" and per ~= "beat" then return nil, 'per must be "bar" or "beat"' end
+  if p.midi and p.trackIndex < 0 then return nil, "the master track holds no MIDI notes" end
+  local segs = grid_segments(api, t0, t1, per)
+  if not segs then return nil, "more than " .. M.MAX_CHORD_SEGMENTS .. " " .. per .. "s in the range: use a shorter range" .. (per == "beat" and ' or per "bar"' or "") end
+  local out = { startTime = r4(t0), endTime = r4(t1), segments = {} }
+  local profiles, bass = {}, {}
+  for i, s in ipairs(segs) do
+    out.segments[i] = { start = s.start, ["end"] = s["end"], bar = s.bar, beat = s.beat }
+    local z = {}
+    for k = 1, 12 do z[k] = 0 end
+    profiles[i], bass[i] = z, -1
+  end
+  if p.midi then
+    local notes, c = heard_notes(api, tr, t0, t1)
+    for _, n in ipairs(notes) do
+      -- First segment the note can touch (segments are in time order)
+      local lo, hi = 1, #segs
+      while lo < hi do
+        local mid = (lo + hi) // 2
+        if segs[mid].q1 <= n.qs then lo = mid + 1 else hi = mid end
+      end
+      for i = lo, #segs do
+        local s = segs[i]
+        if s.q0 >= n.qe then break end
+        local o = math.min(n.qe, s.q1) - math.max(n.qs, s.q0)
+        if o > 0 then
+          local pc = n.pitch % 12 + 1
+          profiles[i][pc] = profiles[i][pc] + o * n.w
+          -- The bass: the lowest note held for at least a quarter of the segment
+          if o >= 0.25 * (s.q1 - s.q0) - EPS and (bass[i] < 0 or n.pitch < bass[i]) then bass[i] = n.pitch end
+        end
+      end
+    end
+    for i = 1, #segs do for k = 1, 12 do profiles[i][k] = r4(profiles[i][k]) end end
+    out.profiles, out.bass = profiles, bass
+    out.notes, out.midiItems, out.audioItems = c.notes, c.midiItems, c.audioItems
+    if c.capped > 0 then out.itemsNotRead = c.capped end
+  end
+  return out
+end
+
+return M