FX Mapping: Manual - FunkybotsEvilTwin/CSIUserGuide GitHub Wiki

Manual FX Mapping

CSI allows users to create custom FX and instrument mappings for one or more control surfaces. These FX Zones function similarly to surface Zones, mapping Widgets (as defined in the surface.txt file) to specific behaviors.

However, while surface Zones assign widgets to Reaper actions, FX Zones map widgets to FX parameter values within plugins, such as:

  • VST, VSTi, VST3, VST3i
  • AU, AUi
  • CLAP
  • JSFX

Note: Reaper and CSI do not distinguish between FX and instruments, so the same mapping principles apply to both.

Creating FX Zones

This section covers how to manually create FX zone files (fx.zon) and activate them in CSI.

CSI also includes a built-in Learn Mode, which is the recommended method for creating fx.zon files. However, in some cases, you may prefer to create them from scratch for greater customization, or for more advanced use-cases like sub-zones and SelectedTrackFX designed to map multiple plugins to the surface simultaneously.

Overview of FX.zon Files

Each plugin requires a unique .zon file placed in the CSI/[SurfaceName]/FXZones/ folder. These plain text files should have the .zon extension. As a best practice, include the plugin format, name, and manufacturer in the filename (e.g., VST3_PluginName_Manufacturer.zon).

When creating a .zon file, note the following:

  • File Management: Organize .zon files by storing them in the FXZones folder. For extensive mappings, consider additional subfolders by manufacturer (e.g., CSI/[SurfaceName]/FXZones/Universal Audio/).
  • Initialization: After creating or manually modifying a fx.zon file, remove all instances of the FX in your project and reinitialize CSI by either:
    • Running the Reaper action "Refresh all surfaces".
    • Opening the CSI preferences in Reaper and clicking OK.
    • Or by restarting Reaper.

Tip: You can streamline manual fx.zon file creation by using templates. Some users create Excel documents or text templates listing surface widgets to speed up mapping. Copy and paste FXParam numbers or actions into the template and export it as a .zon file.

Finding FXParam Numbers

FXParam numbers are essential for mapping FX parameters to surface widgets. There are two methods for identifying these numbers:

Method 1: Enable "Write Params to CSI/ZoneRawFXFiles When FX Inserted"

  1. Open Reaper Preferences and navigate to Control/OSC/Web > CSI > Advanced.
  2. Check the box labeled "Write params to CSI/ZoneRawFXFiles when FX inserted".
  3. Click OK to save the changes.
  4. Insert the desired FX into your project. A file with the FX parameters will be written to the CSI/ZoneRawFXFiles folder.

See the screenshot below of the Advanced preferences screen:
CSI Advanced Preferences

If you were to insert the UAD LA-2A FX, CSI would produce a .txt file in the ZoneRawFXFiles that looks like this, which we will use for mapping our first FX later on this page:

Zone "VST: UAD Teletronix LA-2A Silver (Universal Audio, Inc.)"
	FXParam 0 "Peak Reduct"
	FXParam 1 "Gain"
	FXParam 2 "Comp/Limit"
	FXParam 3 "Emphasis"
	FXParam 4 "Meter"
	FXParam 5 "Mix"
	FXParam 6 "Power"
	FXParam 7 "Bypass"
	FXParam 8 "Wet"
	FXParam 9 "Delta"
ZoneEnd

Method 2: Turn Off the Plugin UI and Count!

An alternate method involves toggling the plugin UI in Reaper:

  1. Open the FX plugin in Reaper.
  2. Click the "UI" button in the plugin menu to hide the plugin's graphical interface.

This replaces the graphical interface with a series of horizontal sliders. The first slider corresponds to FXParam 0, with each subsequent slider incrementing the FXParam number by one.

Mapping Our First FX

Once you identify the FXParam number for each parameter, you can append the FXParam # to actions in your .zon file to map the parameter to a control surface widget. The essential FX Mapping Actions to understand in this for this task are:

FXParam
FXParamNameDisplay
FXParamValueDisplay
FixedTextDisplay

FXParam controls a parameter and maps it to a widget.

FXParamNameDisplay displays the name of the parameter on surfaces with displays. Note: If the parameter name is too long or unclear, use the FixedTextDisplay action followed by an alias in quotes. This method is commonly used in fx.zon files to enhance clarity and formatting.

FXParamValueDisplay shows the current value of the parameter.

For the full list of available FX mapping actions, see FX Mapping Actions.

Example of an FX Zone

Let's start by reviewing a simple fx.zon file, breaking it down into its component parts, and then working backwards to understand how we arrived at this point. In this example, we're using the UAD Teletronix LA-2A Silver plugin, mapped to the widgets on a MCU/X-Touch Universal-style device. While this example may seem intimidating at first, you'll see that it's actually quite easy to understand once we go through it line by line.

Zone "VST: UAD Teletronix LA-2A Silver (Universal Audio, Inc.)" "LA2ASlv"
     Rotary1             FXParam 0 
     RotaryPush1         NoAction
     DisplayUpper1       FixedTextDisplay "Thresh"
     DisplayLower1       FXParamValueDisplay 0

     Rotary2             FXParam 3
     RotaryPush2         NoAction  
     DisplayUpper2       FixedTextDisplay "HF Emph"
     DisplayLower2       FXParamValueDisplay 3

     Rotary3             FXParam 1
     RotaryPush3         NoAction 
     DisplayUpper3       FixedTextDisplay "Output" 
     DisplayLower3       FXParamValueDisplay 1 

     Rotary4             NoAction
     RotaryPush4         FXParam 2 [ 0.0 1.0 ]
     DisplayUpper4       FixedTextDisplay "CompLim" 
     DisplayLower4       FXParamValueDisplay 2

     Rotary5             FXParam 4 [ 0.0 0.50 1.0 ]
     RotaryPush5         NoAction     
     DisplayUpper5       FixedTextDisplay "Meter" 
     DisplayLower5       FXParamValueDisplay 4

     Rotary6             NoAction
     RotaryPush6         NoAction     
     DisplayUpper6       NoAction
     DisplayLower6       NoAction

     Rotary7             NoAction 
     RotaryPush7         NoAction
     DisplayUpper7       NoAction 
     DisplayLower7       NoAction 

     Rotary8             FXParam 8
     RotaryPush8         ToggleFXBypass
     DisplayUpper8       FixedTextDisplay "Wet"
     DisplayLower8       FXBypassedDisplay
ZoneEnd

The First and Last Lines of an FX Zone (Plugin Type, Plugin Name, Plugin Alias)

The first line of an FX zone file must include the plugin name exactly as it appears in Reaper. You can optionally add a plugin alias (short name) for clarity in FX lists.

In the example above, the first line is:

Zone "VST: UAD Teletronix LA-2A Silver (Universal Audio, Inc.)" "LA2ASlv"

  • Zone: Required keyword.

  • Plugin Name: This must match the name exactly as it appears in Reaper, including the plugin format (e.g., VST, VST3) and vendor (Universal Audio, Inc.). Any typo will prevent the mapping from working. If you use multiple versions of a plugin (e.g. VST2, VST3, and CLAP), you would need to create a separate .zon file for type you use.
    Tip: FXParams may differ between plugin formats, so renaming and reusing files may not always work.

  • Alias: The second string, "LA2ASlv", is an alias (or short name). While optional, it’s recommended to create a concise alias for better clarity on your control surface. Without an alias, you may see something generic like VST: UAD, which doesn’t specify the plugin.

The last line of the file is:

ZoneEnd

This is required to close the FX zone definition. Every CSI zone file, FX or otherwise, must end with this keyword.

Our first action

The first FX parameter that has been mapped to a widget in CSI, is FX Param 0 (which happens to be the Threshold control in this plugin) and that's mapped to the Rotary1 widget. So we add the widget name (Rotary1), followed by the CSI action FXParam and the number 0, which represents the plugin parameter to assign to the widget. Reminder: we identified the FXParam # by using the methods outlined in Finding FXParam Numbers.

     Rotary1             FXParam 0

See FX Mapping Actions for the full list of available FX mapping actions.

Adding some displays for parameter name and value

We then see...

     RotaryPush1         NoAction     
     DisplayUpper1       FixedTextDisplay "Thresh"
     DisplayLower1       FXParamValueDisplay 0

RotaryPush1 "NoAction" says that when this FX.zon is active, RotaryPush1 should not do anything.

DisplayUpper1 will show the word “Thresh” when this zone is active. This is useful if you have limited character displays and FX Params may have long names. Alternately, you could have used the FXParamNameDIsplay action as shown below:

     DisplayUpper1       FXParamNameDisplay 0

…this action will display the full parameter name, versus the alias that was created using the FixedTextDisplay action. The 0 that follows the FXParamNameDisplay action is FXParam #. We'll get into that in a second.

The next line shows

     DisplayLower1       FXParamValueDisplay 0

This will display the value of the FX Parameter being controlled.

Our first "toggle" action and using NoAction to reserve parameters

Jumping further ahead you see...

     Rotary4             NoAction
     RotaryPush4         FXParam 2 [ 0.0 1.0 ]
     DisplayUpper4       FixedTextDisplay "CompLim" 
     DisplayLower4       FXParamValueDisplay 2

Here, turning the Rotary encoder does nothing due to the NoAction line, but pressing RotaryPush4 will toggle the Comp/Limiter parameter. The syntax [ 0.0 1.0 ] following the FXParam means "each press should toggle between the minimum and maximum values."

In CSI, all FX parameters are normalized to a range of 0.0 to 1.0. This syntax specifies that the parameter toggles between its lowest and highest values. You’ll also notice similar syntax used to step through three parameters with the "Meter" parameter on the rotary encoder in this .zon example. For more details, see the Stepped Params and Toggles page.

Finally, I want to highlight the use of NoAction for controls on the surface that don’t have an assigned action in the FX.zon file. Why is this important?

  • Best Practice: It ensures you’re not inadvertently changing parameters on your track or elsewhere when the FX.zon file is active.
  • Clean Displays: It helps ensure unused displays are cleared out appropriately.
     Rotary6             NoAction
     RotaryPush6         NoAction     
     DisplayUpper6       NoAction
     DisplayLower6       NoAction

Save the .zon File

The final step is to save the .zon file. These are simply plain text files where you rename the file extension to .zon. In this example, a recommended name could be VST2_UAD_LA2A_Silver_Universal_Audio.zon. Avoid using spaces in the file name.

.zon files must be saved in the following directory:
CSI/[SurfaceName]/FXZones/

Those are the basics of creating an fx.zon file.