ReaFruit reference

For scripters and integrators: the ReaScript API, script parameter boxes, the MCP server, REAPER action ids, settings keys and the files ReaFruit reads and writes. The Manual covers the editor itself.

ReaScript API #

The extension exports a ReaFruit_* family to ReaScript. Lua and EEL2 call reaper.ReaFruit_CountNotes() and friends; REAPER's IDE completes them and Help › ReaScript documentation lists them. Scripts are ordinary ReaScripts: they run from the Actions list, keys, toolbars and gear › Scripts. Python reaches extension functions only through a generated ctypes module, which this version does not ship.

Conventions #

• Times are absolute project quarter notes (QN). Pitches are MIDI note numbers (60 = C4).
• A note's identity is its index, 0 to CountNotes() - 1, stable between writes. DeleteNote shifts later indices down; a write that rebuilds the model (EndEdit reports it, Refresh, an undo) may reorder them.
• Failures return false or -1; ReaFruit_GetLastError() says why. Out-parameters become extra return values in Lua.
• Calls that write refuse while a mouse gesture, a parameter-box session or a batch is in progress; the error names the reason.

Editor and info #

Notes #

Batches #

Every edit above writes the take at once as its own undo step. ReaFruit_BeginEdit() … ReaFruit_EndEdit(desc) makes them one write and one undo step named desc; EndEdit also returns whether the model reloaded. Inside a batch indices stay put, and actions that write the take are refused until it ends. Finish a batch in the same pass: one left open is written at the editor's next frame as "script edit". Per-note automation of moved notes follows; deleted notes' points are cleaned.

Clips, actions, settings #

The JSON gateway #

ReaFruit_CallTool(name, argsJson) runs any of the 30 MCP tools and returns the result's length (and whether it is an error); ReaFruit_GetResult(offset) hands the JSON text back in chunks. Unlike the MCP client, a script may place and move notes, and these calls never count against the license trial.

The helper library #

At load, the extension writes Scripts/ReaFruit/reafruit.lua into the resource folder: a JSON codec and wrappers. rf.notes(), rf.selected(), rf.targets() (the selection, or every note), rf.set(idx, {vel=, slide=, …}), rf.insert{qs=, len=, pitch=}, rf.delete, rf.select, rf.edit(fn, desc) (one undo step with error safety), rf.run, rf.setting, rf.tool(name, args) with Lua tables, rf.status(), rf.mouse(), rf.snap(qn), rf.boxes(title, defs, apply, done), and the automation wrappers rf.set_note_auto, rf.note_auto, rf.set_auto_points, rf.auto_points, rf.delete_auto_points, rf.lane_key(). A shipped file's first line is a marker; files with the marker are updated when a new version ships, files without it are yours.

package.path = reaper.GetResourcePath() .. '/Scripts/ReaFruit/?.lua;' .. package.path
local rf = require('reafruit')
rf.require_open()
rf.edit(function()
  for _, n in ipairs(rf.selected()) do rf.set(n.idx, { vel = math.min(127, n.vel + 10) }) end
end, 'Louder')

Script parameter boxes #

A script can put up its own parameter boxes, at most eight, with the keep and discard pair, and preview its edits live as the user turns them, like Humanize.

Box definitions #

ReaFruit_BoxesBegin(title, boxesJson) opens them from a JSON array. Each box has a name, a type and an optional picture: bar (a range's default), knob, text (a choice's default), switch (a toggle's), die (a seed's).

Kept values come back the next time boxes with the same title open; "remember": false opts a box out, and a seed rolls anew each time unless it has a default.

The poll loop #

The script polls ReaFruit_BoxesPoll() from a defer loop.

Automation previews too: what CallTool writes with the automation tools lands in REAPER at once and is restored on every changed and on a cancel. ReaFruit_BoxesSetValue(box, value) moves a box; ReaFruit_BoxesEnd(keep) closes them from the script. A script that stops polling for 1.5 s has its boxes cancelled; closing the editor or switching clips drops them. The helper wraps the whole loop as rf.boxes(title, defs, apply, done).

Native MIDI editor scripts #

gear › Scripts › Run as native MIDI editor script…, or a key slot assigned "as native", runs a script written for REAPER's MIDI editor against ReaFruit's take. reafruit_compat.lua redefines MIDIEditor_GetActive, MIDIEditor_GetTake, MIDIEditor_EnumTakes and MIDIEditor_GetMode around the editor's take, maps MIDIEditor_OnCommand to the editor's actions where one exists (select all, unselect, delete, copy, paste, cut, undo, redo, semitone and octave moves, grid nudges) and refreshes the editor afterwards.

MCP server #

An embedded Model Context Protocol server lets an LLM client read and edit the notes and settings of the running editor. It is off by default and listens only on localhost. It is the editor's one paid feature: the first 100 tool calls are free, status calls never count, and a license removes the limit. Enable it under gear › Advanced › MCP server (LLM access on localhost); the port submenu offers 7323 (the default), 7324, 7325, 8765 and 9765.

Client setup #

# Claude Code
claude mcp add --transport http reafruit http://127.0.0.1:7323/mcp

# stdio-only clients (Claude Desktop)
npx mcp-remote http://127.0.0.1:7323/mcp --allow-http

Tools #

Positions are project QN, pitches MIDI note numbers. Every note row carries its name, its clip and the bar and beat the ruler shows. status, list_tracks and the settings answer while the editor is closed; the note tools need it open on a MIDI take. Required parameters are in bold.

Controls are keyed by the lane target: track envelopes by name, FX parameters by plugin and parameter, MIDI controllers as cc:<n> or cc:bend (@<chan> for one channel, /<item> for another item), or by the names mod, expression, breath, sustain and bend. Lanes the editor writes itself come back locked.

run_action names #

Names marked * change notes and are refused over MCP; scripts may run them.

play_stop go_to_start select_all deselect clear_selection select_color toggle_ghosts follow bass_line pan_left pan_right pan_up pan_down zoom_in zoom_out tool_draw tool_paint tool_delete tool_mute tool_slice tool_select

duplicate* glue* legato* legato_slide* chop* undo* redo* redo_alt* octave_up* octave_down* transpose_up* transpose_down* nudge_left* nudge_right* recolor* quantize_quick* delete_notes* delete_notes_alt* slide_mode* vibrato_mode*

set_setting keys #

Rules and refusals #

• Notes are the user's. The server never creates or moves notes: add_notes is refused, edit_notes refuses position and pitch fields, run_action refuses the actions marked above. The model edits note parameters (velocity, channel, colour and articulation, mute, selection, slide and vibrato with depth, tension and rate), deletes, selects, and shapes automation, CC lanes and the maps.
• Note ids are indices valid only for the version they came with; a stale version is refused, naming the current one. A reply saying reloaded: true means every id may have changed.
• One undo step per mutating call.
• Refusals are tool errors with the reason: the editor is closed, a mouse gesture or a box session is in progress, an edit is still being written. status reports the same as editable and blocked.
• The handshake explains slide and vibrato notes as the editor renders them, and asks the model to use them where the music calls for it; status carries mpe and bend_range so slides stay within reach.

Transport #

A loopback listener thread reads each request and hands it to REAPER's main thread, which runs it against the editor's model between frames, never inside one. A request the main thread does not reach within 5 s (REAPER busy, a modal dialog up) gets 504. POST one JSON-RPC message to /mcp and read application/json back; no SSE stream (GET answers 405), stateless, protocol version 2025-06-18.

REAPER actions #

Main section #

Named command ids, for reaper.NamedCommandLookup("_REAFRUIT_MIDI_EDITOR") and the like. Each is listed as ReaFruit MIDI Editor: ….

Scripts run from gear › Scripts are registered in the main section the first time they run.

The editor section #

The Actions window's section ReaFruit MIDI Editor (section id 0x52464D45) holds one command per editor action. The command id is 42000 plus the action's index below; the name is what reafruit_keys.ini and ReaFruit_RunAction use. Scope: A = anywhere, R = piano roll only, S = Sheet Music Mode, I = sheet note input only.

Settings and files #

reaper-extstate.ini #

Settings persist in REAPER's reaper-extstate.ini under the section [FL_PianoRoll]. The keys below are the user-facing ones; lic_*, upd_*, note_done, defaults_v and script_boxes:* are the extension's own bookkeeping.

Track and clip data #

The scale is also saved per project. Note colours, slides, vibrato and per-note automation are stored as tags in the take, so a project opened without the extension keeps playing.

Data folders #

reafruit_keys.ini #

One line per action, action = [ctrl+][shift+][alt+]key, for example duplicate = ctrl+shift+d. ctrl means Cmd on macOS; cmd and option are accepted as aliases for ctrl and alt; none unbinds. Key names: letters, digits, f1 to f24, up down left right space enter tab escape backspace delete insert home end pageup pagedown comma period slash semicolon apostrophe minus equals leftbracket rightbracket backslash grave and the keypad. Missing lines keep their defaults; a shortcut set in REAPER's Actions window always wins. The file is created with the defaults when missing and re-read when the editor opens.

ReaFruit MIDI Editor v0.9.6-beta · Manual