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

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