setup_fx_chain
Add and configure FX chains on one or many REAPER tracks in a single call, applying plugin parameters in a deterministic order required by some plugins.
Instructions
Add and/or configure FX — the only tool for this, for one plugin
on one track just as much as many plugins across many tracks. There
is no separate single-shot "add one FX" or "set one param" tool:
a single fx_chain entry with one track is exactly as simple as
those would be, and this is the only path that writes params in the
order some plugins require — e.g. FabFilter Pro-Q 3/Pro-C 2 need a
band's Used/Enabled flag written before its other params (Frequency,
Gain, Shape, ...), or the write has no audible effect and silently
looks like it didn't work.
Params are applied in a fixed, deterministic order (not raw dict iteration order) specifically because some plugins (confirmed: FabFilter Pro-Q 3/Pro-C 2) crash if a band's Used/Enabled flag isn't written before its other params — this already handles that, no need to sequence params yourself.
Example — add the same plugin (e.g. an EQ) to 5 different tracks in one call:
[
{"track_index": 0, "fx_chain": [{"name": "FabFilter Pro-Q 3"}]},
{"track_index": 1, "fx_chain": [{"name": "FabFilter Pro-Q 3"}]},
{"track_index": 2, "fx_chain": [{"name": "FabFilter Pro-Q 3"}]},
{"track_index": 3, "fx_chain": [{"name": "FabFilter Pro-Q 3"}]},
{"track_index": 4, "fx_chain": [{"name": "FabFilter Pro-Q 3"}]}
]fx_chain can hold more than one plugin per track too — a whole
Saturn + Pro-Q 3 + Pro-C 2 chain, with params, added to several
tracks, is still one call.
Example — set up Band 1 (Low Cut) and Band 2 (High Shelf, +2dB) on an EQ that's already track 0's fx_index 1, by index (skips the fuzzy name-matching lookup, marginally faster for a big batch):
[{"track_index": 0, "fx_chain": [
{"fx_index": 1, "params_by_index": {
"0": 1.0, "1": 1.0, "2": 0.218, "8": 0.25
}},
{"fx_index": 1, "params_by_index": {
"13": 1.0, "14": 1.0, "15": 0.845, "16": 0.533, "21": 0.375
}}
]}](Same fx_index reused across entries is fine — each entry is an
independent set of param writes, not a new FX add.)
Args:
tracks: JSON array, one object per track:
{"track_index": int, "fx_chain": [...]}, where
track_index is 0-based, or -1 for the master track —
so a full mastering chain (EQ -> compressor -> saturation ->
limiter, with params) can be built in one call, without
engine_master wiping the existing chain. Each fx_chain
entry is one FX to add-and/or-configure:
- "name": str — add new via fuzzy match (default mode).
"add_mode": "find_or_add" reuses an existing instance of
that plugin instead of adding a duplicate;
"add_mode": "find_only" fails if it's not already there.
- "fx_index": int — target an FX that's already in the
chain (from an earlier setup_fx_chain call, or already
present in the project) instead of adding one.
- "params": {name: value} — set params by fuzzy name
match (e.g. "Band 1 Frequency"). Values 0.0-1.0
normalized.
- "params_by_index": {"<index>": value} — same, by exact
0-based param index (keys are strings — JSON object keys
always are). Skips the per-param name lookup.
- "preset": str — load a preset by name after params are
applied.
- "named_config": {key: value} — plugin state that isn't
an automatable param, written before params, e.g.
{"BANDENABLED4": "1"} to switch on ReaEQ's 5th band.
Each key is read back and reported in named_config_set
with ok — trust that, not the write.
Every failure is reported per-item in the response's summary
({"error": "..."} on that track or that one param), never a hard
abort of the whole batch — a bad track_index, an FX name that
doesn't resolve, or a param name/index that doesn't match anything
each fail on their own without losing whatever else in the same
call succeeded. Check summary rather than assuming a
non-throwing call means every item landed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tracks | Yes |