reaper-control/.sdd/changes/archive/reascript-first/proposal.md

Proposal: ReaScript-First Built-in Plugin Configuration

Intent

RPPBuilder writes .rpp text that REAPER loads, but built-in plugins (ReaEQ, ReaComp, ReaVerb, etc.) need the REAPER API (TrackFX_AddByName, TrackFX_SetParam) to configure parameters correctly. Text-mode VST "ReaEQ" "reaeq.dll" loads the plugin but leaves all 19 param slots at zero — no EQ curve, no compression threshold. ReaScript already handles verify/render; it must also handle built-in plugin insertion and parameter configuration while RPPBuilder keeps generating VST3/MIDI/audio structure.

Scope

In Scope

• New ReaScript actions: add_track, add_fx, add_midi_item, configure_fx_params
• ReaScriptCommand dataclass extended with plugins_to_add: list[PluginDef], fx_params: list[dict]
• ReaScriptGenerator generates script blocks for InsertTrackAtIndex, TrackFX_AddByName, CreateNewMIDIItemInProj, MIDI_InsertNote, TrackFX_SetParam
• scripts/run_in_reaper.py supports multi-action pipeline: skeleton → inject plugins → verify → render
• commands.py decoupled: action dispatch mapping, ReaScriptResult gains added_plugins: list[tuple[str, int]]
• RPPBuilder marks built-in plugins with params field; ReaScript reads these and applies via API

Out of Scope

• VST3 plugin insertion via ReaScript (RPPBuilder handles these)
• ReaScript-based arrangement/track ordering (RPPBuilder remains source of truth)
• OSC/HTTP-based REAPER control
• Multi-DAW support

Capabilities

New Capabilities

• reascript-builtin-fx: ReaScript generates code to insert built-in REAPER plugins with configured parameters via the native API, reading a plugins_to_add section from the command JSON.

Modified Capabilities

• reascript-generator: (existing) expands beyond verify/calibrate/render to support add_track, add_fx, add_midi_item, configure_fx_params actions with action dispatch.

Approach

Hybrid pipeline: RPPBuilder writes a skeleton .rpp with VST3 plugs + MIDI + audio. ReaScript then executes:

1. Open skeleton .rpp
2. Add tracks reserved for built-in plugins (InsertTrackAtIndex)
3. Insert FX by name (TrackFX_AddByName("ReaEQ"))
4. Configure params (TrackFX_SetParam(track, fx_idx, param_idx, value))
5. Add MIDI items/notes for ReaScript-generated MIDI (if needed)
6. Verify all FX → calibrate volumes → render → measure LUFS

ReaScriptCommand.action becomes an ordered list: ["add_plugins", "verify_fx", "calibrate", "render"]. ReaScriptGenerator._build_script() dispatches per-action code blocks.

Affected Areas

Area	Impact	Description
src/reaper_scripting/commands.py	Modified	New action types + plugins_to_add field
src/reaper_scripting/__init__.py	Modified	New script generation blocks for built-in FX
scripts/run_in_reaper.py	Modified	Multi-action pipeline orchestration
src/reaper_builder/__init__.py	Modified	Mark built-in plugins in RPP with params dict
tests/test_reaper_scripting.py	Modified	New tests for add_fx/configure_fx_params

Risks

Risk	Likelihood	Mitigation
Built-in plugin API missing in REAPER version	Low	API check in generated script; fallback to text-only
Param indices differ across REAPER versions	Medium	Pin known indices; version-detect at script startup
Multi-action execution breaks existing tests	Medium	Extensible action dispatch; existing "calibrate" action preserved

Rollback Plan

1. Revert commands.py to single-action model (backward compat: action: "calibrate" still works)
2. Revert _build_script() to single-block generation
3. RPPBuilder changes are additive (new params field); no rollback needed
4. Existing 298 tests must remain green throughout

Dependencies

• REAPER v7+ with Python ReaScript
• No new Python packages

Success Criteria

• ReaScriptCommand(action="add_plugins") generates valid Python that calls TrackFX_AddByName and TrackFX_SetParam
• Built-in plugin (ReaEQ) loaded with correct params in generated .rpp verified by REAPER
• Existing 298 tests pass unchanged
• scripts/run_in_reaper.py runs multi-action pipeline end-to-end
• Generated ReaScript handles missing API gracefully with check_api() guard