FX Parameter Mapping Actions - FunkybotsEvilTwin/CSIWiki GitHub Wiki
CSI allows you to map plugin parameters to your control surface. See [FX-Mapping:-Manual]] for details on how to create a .zon file for your effect or instrument (they're called FX zones, but work equally well for instruments). You'll also want to see [Finding FXParam Numbers for a quick and easy to way to get the FX Param # that you'll need for the mapping.
FX Action List
- FXParam
- FXNameDisplay
- FXParamNameDisplay
- FXParamValueDisplay
- FXMenuNameDisplay
- FocusedFXParam
- FocusedFXParamNameDisplay
- FocusedFXParamValueDisplay
- ToggleEnableFocusedFXMapping
- ToggleEnableFocusedFXParamMapping
- ToggleFXBypass
- FXBypassDisplay
- ToggleFXOffline
- FXOfflineDisplay
- FXGainReductionMeter
- GoFXSlot
- ShowFXSlot
- HideFXSlot
- TCPFXParam
- TCPFXParamNameDisplay
- TCPFXParamValueDisplay
- JSFXParam
- RemapAutoZone
- AutoMapFX
FXParam
FXParam is the CSI action to control a plugin parameter. Let's say we've followed the steps in Finding FXParam Numbers and we can see that ReaComp's parameter list looks something like this...
Zone "VST: ReaComp"
FXParam 0 "Thresh"
FXParam 1 "Ratio"
FXParam 2 "Attack"
FXParam 4 "Release"
...
ZoneEnd
If you want to map these first four parameters to the first four rotary knobs on your surface, you'd use the following syntax (in this case my widget names are RotaryA1 through A4, yours may vary):
Zone "VST: ReaComp"
RotaryA1 FXParam 0
RotaryA2 FXParam 1
RotaryA3 FXParam 2
RotaryA3 FXParam 4
ZoneEnd
Alternatively, if you wanted to include the names (not as displays, that's coming in the next section, but just for easy reference) this is also acceptable...
RotaryA1 FXParam 0 "Thresh"
RotaryA2 FXParam 1 "Ratio"
RotaryA3 FXParam 2 "Attack"
RotaryA3 FXParam 4 "Release"
...as is this method (using trailing comments)...
RotaryA1 FXParam 0 //Thresh
RotaryA2 FXParam 1 // Ratio
RotaryA3 FXParam 2 // Attack
RotaryA3 FXParam 4 // Release
FXParamNameDisplay
If you wanted to add in the name of the the Parameter to the corresponding display, that would look like this...
DisplayUpperA1 FXParamNameDisplay 0 "Thresh"
RotaryA1 FXParam 0
DisplayUpperA2 FXParamNameDisplay 1 "Ratio"
RotaryA2 FXParam 1
DisplayUpperA3 FXParamNameDisplay 2 "Attack"
RotaryA3 FXParam 2
DisplayUpperA3 FXParamNameDisplay 3 "Release"
RotaryA3 FXParam 4
FXParamValueDisplay
And if you wanted to use one of your displays to show the actual parameter value (e.g. "32ms" or "220hz") on your displays, there is a CSI action for that as well. Combining all three examples together you'd end up with the following:
DisplayUpperA1 FXParamNameDisplay 0 "Thresh"
DisplayLowerA1 FXParamValueDisplay 0
RotaryA1 FXParam 0
/
DisplayUpperA2 FXParamNameDisplay 1 "Ratio"
DisplayLowerA2 FXParamValueDisplay 1
RotaryA2 FXParam 1
/
DisplayUpperA3 FXParamNameDisplay 2 "Attack"
DisplayLowerA3 FXParamValueDisplay 2
RotaryA3 FXParam 2
/
DisplayUpperA4 FXParamNameDisplay 3 "Release"
DisplayLowerA4 FXParamValueDisplay 3
RotaryA4 FXParam 4
You may notice in the above example I broke up each set of widgets with an empty row with a single / character. This essentially "comments out" the empty line, but will make your .zon file easier to read and troubleshoot later on, so I recommend this as a best practice when grouping together multiple widgets for a single FX parameter.
FXNameDisplay
If you want your display to show the FX Name, you could simply add a line to one of your display widgets such as:
DisplayUpperA1 FXNameDisplay
Which would display on your surface (continuing the example from above with ReaComp):
VST: ReaComp (Cockos)
FXMenuNameDisplay
FXMenuNameDisplay is typically used in TrackFXMenu and SelectedTrackFXMenu zones to show the name of the FX loaded into the corresponding FX slot. If there is a plugin alias in the fx.zon file, it will display the alias. Otherwise, it will display the full plugin name from the first line of the zone file, including the plugin format and any vendor information. It's recommended that users create a plugin alias when creating fx.zon files for this reason. See FX and Instrument Mapping for more details.
If there is no fx.zon for the corresponding FX in the slot. CSI will show "NoMap" on the display.
Zone "TrackFXMenu"
DisplayUpper| FXMenuNameDisplay
DisplayLower| FXBypassDisplay
Rotary| NoAction
RotaryPush| ShowFXSlot
RotaryPush| GoFXSlot
Mute| ToggleFXBypass
Left TrackFXMenuBank -1
Right TrackFXMenuBank 1
ZoneEnd
GoFXSlot
GoFXSlot is used in TrackFXMenu and SelectedTrackFXMenu zones to activate the FX mapping for the corresponding FX slot. See the example below from a TrackFXMenu where pressing RotaryPush will activate the FX map for the corresponding FX.
Zone "TrackFXMenu"
DisplayUpper| FXMenuNameDisplay
DisplayLower| FXBypassDisplay
Rotary| NoAction
RotaryPush| ShowFXSlot
RotaryPush| GoFXSlot
Mute| ToggleFXBypass
Left TrackFXMenuBank -1
Right TrackFXMenuBank 1
ZoneEnd
ShowFXSlot, HideFXSlot
ShowFXSlot will float the GUI for the corresponding FX slot on the surface. When paired with GoFXSlot as shown below, activating the FX slot on your surface will both map the FX on the surface and open the GUI on screen.
Zone "TrackFXMenu"
DisplayUpper| FXMenuNameDisplay
DisplayLower| FXBypassDisplay
Rotary| NoAction
RotaryPush| ShowFXSlot
RotaryPush| GoFXSlot
Mute| ToggleFXBypass
Left TrackFXMenuBank -1
Right TrackFXMenuBank 1
ZoneEnd
HideFXSlot will similarly close the GUI. This can be paired with the OnZoneDeactivation virtual widget to automatically close the GUI when the FX mapping is disabled as shown below.
Zone FXEpilogue
OnZoneDeactivation HideFXSlot
Plugin ClearFXSlot
ZoneEnd
ToggleFXBypass
Use this action in a SelectedTrackFXMenu or TrackFXMenu zone to assign toggling the FX Slot to a button.
Zone "TrackFXMenu"
DisplayUpper| FXMenuNameDisplay
Rotary| NoAction
RotaryPush| GoFXSlot
Mute| ToggleFXBypass
Left TrackFXMenuBank -1
Right TrackFXMenuBank 1
ZoneEnd
FXBypassDisplay
If you want to add the FX state ("Enabled" or "Bypass") to the SelectedTrackFXMenu or TrackFXMenu you would utilize the FXBypassDisplay action as shown below:
Zone "TrackFXMenu"
DisplayUpper| FXMenuNameDisplay
DisplayLower| FXBypassDisplay
Rotary| NoAction
RotaryPush| GoFXSlot
Mute| ToggleFXBypass
Left TrackFXMenuBank -1
Right TrackFXMenuBank 1
ZoneEnd
ToggleFXOffline, FXOfflineDisplay
Use ToggleFXOffline to change the FX status to "offline" in Reaper. Offline FX is similar to Bypass, but it removes the plugin from memory and additional processing. In the below example, it's assigned to Shift+Mute. The corresponding display action is FXOfflineDisplay.
Zone "SelectedTrackFXMenu"
DisplayUpper| FXMenuNameDisplay
DisplayLower| FXBypassDisplay
Shift+DisplayLower| FXOfflineDisplay
Rotary| NoAction
RotaryPush| GoFXSlot
Mute| ToggleFXBypass
Shift+Mute| ToggleFXOffline
Left SelectedTrackFXMenuBank -1
Right SelectedTrackFXMenuBank 1
RecordArm| NoAction
Solo| NoAction
Select| NoAction
Fader| NoAction
ZoneEnd
FocusedFXParam
FocusedFXParam is a CSI action that allows you to assign a control on your surface to the last touched plugin parameter. This can be a very fast way to assign plugin parameters to your surface without having to create an fx.zon in advance. This is very useful for quickly writing automation or tweaking a plugin parameter.
For instance, let's say you already have Fader1 on your surface mapped to track volume of the Selected track, and you want to map Shift+Fader1 the last-touched FX parameter. Your .zon file might look like this...
Zone "Channel"
Fader1 TrackVolume
Shift+Fader1 FocusedFXParam
ZoneEnd
Now, when you enable the Shift modifier, Fader1 will control the last touched plugin parameter. If you want to change the parameter you're controlling, just use your mouse and move the next plugin parameter. Your surface will update to control the new parameter as long as you're still in Shift mode (or when you next hold down the shift modifier). Tip: a quick tap of Shift latches the shift modifier - very handy in this example.
You can also have a FocusedFXParam zone. Example: I have this in my buttons.zon...
Zone "Buttons"
F2 ToggleEnableFocusedFXParamMapping
ZoneEnd
Which then calls up this FocusedFXParam.zon.
Zone "FocusedFXParam"
Fader1 FocusedFXParam
DisplayUpper1 FocusedFXParamNameDisplay
DisplayLower1 FocusedFXParamValueDisplay
ZoneEnd
FocusedFXParamNameDisplay and FocusedFXParamValueDisplay
As shown in the FocusedFXParam.zon above, let's say our surface has displays and we want the upper display to show the Parameter Name and lower display to show the parameter value whenever the FocusedFXParam zone is active. The FocusedFXParamNameDisplay and FocusedFXParamValueDisplay actions are designed to do just that.
Zone "FocusedFXParam"
Fader1 FocusedFXParam
DisplayUpper1 FocusedFXParamNameDisplay
DisplayLower1 FocusedFXParamValueDisplay
ZoneEnd
FXParamRelative
FXParamRelative uses the value from the controller as a delta and adds it to the current parameter value. If the value is negative, that amounts to subtracting it from the current parameter value.
SomeWidget FXParamRelative 4
FXGainReductionMeter
A small handful of plugins (I believe VST3) will report Gain Reduction values to the host, allowing you to see how much compression (for example) is taking place. If the plugin supports this, you can assign this to a widget in CSI.
VUMeter FXGainReductionMeter
ToggleEnableFocusedFXMapping
FocusedFX mapping is enabled by default. This means if you have a fx.zon file for a particular FX/instrument plugin, and open the GUI in Reaper, that mapping will become activated on your surface as the default behavior. You can toggle this behavior off and on by assigning a button to the ToggleEnableFocusedFXMapping action as shown below:
SomeButton ToggleEnableFocusedFXMapping
But what if you don't want FocusedFXMapping on by default? Since the default toggle state is "on", you can add "OnInitialization ToggleFocusedFXMapping" to flip it to off when CSI starts up as shown below:
Zone Home
OnInitialization ToggleEnableFocusedFXMapping
IncludedZones
"Buttons"
"Track"
"MasterTrack"
IncludedZonesEnd
AssociatedZones
"SelectedTrackFXMenu"
"SelectedTrackSend"
"SelectedTrackReceive"
"TrackFXMenu"
"TrackSend"
"TrackReceive"
AssociatedZonesEnd
ZoneEnd
ToggleEnableFocusedFXParamMapping
Another feature of CSI is the ability to have the last touched (or "focused") FX parameter automatically mapped to a widget. This behavior can be toggled off and on using the ToggleEnableFocusedFXParamMapping action.
Example: you may have this assigned to a button such as:
Zone "Buttons"
User ToggleEnableFocusedFXParamMapping
ZoneEnd
Then have a fader or widget or even a whole SubZone assigned to the Focused FX Param.
Zone "FocusedFXParam"
Fader1 FocusedFXParam
DisplayUpper1 FocusedFXParamNameDisplay
DisplayLower1 FocusedFXParamValueDisplay
F2 LeaveSubZone
ZoneEnd
TCPFXParam, TCPFXParamValueDisplay, TCPFXParamNameDisplay
CSI allows it to automatically map widgets to the TCP fx on the selected track. This has the benefit of allowing a single zone to control multiple FX on the same channel and automatically update as you navigate from track to track. If you've ever used Cubase's Quick Controls, this is a very similar workflow.
The SelectedTrackTCPFX zone, acts as a template that dictates the mapping of TCP FX. The TCPFXParam, TCPFXParamValueDisplay, and TCPFXParamNameDisplay actions are all used to dictate how those FXParams are mapped to your surface. See the example below for an MCU/X-Touch style surface.
Zone "SelectedTrackTCPFX"
DisplayUpper1 TCPFXParamNameDisplay 0
DisplayLower1 TCPFXParamValueDisplay 0
Rotary1 TCPFXParam 0
DisplayUpper2 TCPFXParamNameDisplay 1
DisplayLower2 TCPFXParamValueDisplay 1
Rotary2 TCPFXParam 1
DisplayUpper3 TCPFXParamNameDisplay 2
DisplayLower3 TCPFXParamValueDisplay 2
Rotary3 TCPFXParam 2
DisplayUpper4 TCPFXParamNameDisplay 3
DisplayLower4 TCPFXParamValueDisplay 3
Rotary4 TCPFXParam 3
DisplayUpper5 TCPFXParamNameDisplay 4
DisplayLower5 TCPFXParamValueDisplay 4
Rotary5 TCPFXParam 4
DisplayUpper6 TCPFXParamNameDisplay 5
DisplayLower6 TCPFXParamValueDisplay 5
Rotary6 TCPFXParam 5
DisplayUpper7 TCPFXParamNameDisplay 6
DisplayLower7 TCPFXParamValueDisplay 6
Rotary7 TCPFXParam 6
DisplayUpper8 TCPFXParamNameDisplay 7
DisplayLower8 TCPFXParamValueDisplay 7
Rotary8 TCPFXParam 7
ZoneEnd
JSFXParam
The JSFXParam action is used when mapping Reaper's JS effects. These effects do not used normalized parameter ranges like VST, VST3, AU, CLAP fx, and thus require their own action type to alert CSI of the non-normalized ranges. Note: you may still encounter issues with JSFXParams depending on the plugin and how it's range is configured.
Here's an example from the JS Chorus fx.
Zone "JS: Chorus (Stereo)" "Chorus"
FXTwisterFXLayout "A" 1 JSFXParam 0 "Chorus Length (ms)"
FXTwisterFXLayout "A" 2 JSFXParam 1 "Number Of Voices"
FXTwisterFXLayout "A" 3 JSFXParam 2 "Rate (Hz) (0=tempo sync)"
FXTwisterFXLayout "A" 4 JSFXParam 3 "Pitch Fudge Factor"
FXTwisterFXLayout "A" 5 JSFXParam 4 "Wet Mix (dB)"
FXTwisterFXLayout "A" 6 JSFXParam 5 "Dry Mix (dB)"
FXTwisterFXLayout "A" 7 JSFXParam 6 "Channel Rate Offset (Hz)"
FXTwisterFXLayout "A" 8 JSFXParam 7 "Tempo Sync (fraction of whole note)"
FXTwisterFXLayout "B" 1 JSFXParam 8 "Bypass"
FXTwisterFXLayout "B" 2 JSFXParam 9 "Wet"
FXTwisterFXLayout "B" 3 JSFXParam 10 "Delta"
FXTwisterFXLayout "B" 4 JSFXParam -1 ""
FXTwisterFXLayout "B" 5 JSFXParam -1 ""
FXTwisterFXLayout "B" 6 JSFXParam -1 ""
FXTwisterFXLayout "B" 7 JSFXParam -1 ""
FXTwisterFXLayout "B" 8 JSFXParam -1 ""
ZoneEnd
RemapAutoZone
RemapAutoZone allows you to re-order AutoGenerated FX Zone parameters from within Reaper. No need to edit text files just to move the parameters around! This also allows you to change the plugin alias, along with parameter aliases.
First, map a widget to the new RemapAutoZone action. Example:
Zone "Buttons"
F4 RemapAutoZone
ZoneEnd
Next, You need to activate an auto generated Zone with either a Focused FX Zone or an FXSlot Zone via FXMenu.
With the FX active on your surface, trigger the RemapAutoZone action -- e.g. press F4
A new window will appear.
You can directly edit the FX alias at the top.
The auto generated Zone lines appear in a list box.
Click to select an item.
Press the Edit button to edit the display text.
To reorder the item you can press the U [up] and D [down] buttons. With a row selected, you can also drag outside the list box to reorder -- you cannot drag inside the list box due to some list box limitations. If you are on a Mac, you can also use the keyboard left/right arrow keys (currently, this doesn't appear to work on PC).
Press Save to apply the changes.
AutoMapFX
When the AutoMapFX is engaged, an fx.zon will be produced for the focused FX in Reaper. The FX parameters will simply be mapped in sequential order to the widgets defined in your SurfaceFXLayout and FXLayouts files. See FX-Mapping:-Automapping,-Learn-Mode,-and-Remap-Window for more details.
Zone "Buttons"
Aux AutoMapFX