FX Mapping: Learn Mode - FunkybotsEvilTwin/CSIUserGuide GitHub Wiki

Learn Mode Overview

CSI enables users to create custom FX and instrument mappings that can be assigned to one or more control surfaces. These FX Zones function similarly to surface Zones by mapping Widgets, as defined in the surface.txt file, to specific behaviors.

However, while surface Zones bind widgets to Reaper actions, FX Zones map widgets to parameter values within FX plugins (e.g., VST, VSTi, VST3, VST3i, AU, AUi, CLAP, JSFX, etc.).

What is Learn Mode?

Learn Mode provides an intuitive way to map FX and instruments, functioning similarly to many MIDI learn systems in plugins:

  1. Move a control on your surface.
  2. Move a control in the plugin UI.
  3. Press Link to establish the connection.

This allows for quick and efficient mapping of FX parameters to physical controls on your device.

Important Notes

  • Reaper and CSI do not distinguish between instruments and FX, so the same mapping principles apply to both.
  • FX Learn Mode is designed for creating single-plugin FX maps.
    • It cannot be used to create FX Sub-Zones or SelectedTrackFX zones that map multiple FX simultaneously.

For more advanced mapping techniques, refer to the FX Mapping: Manual section.

Using Learn Mode

Once configured properly (more on that further below), the high-level process is:

  1. Focus the FX in Reaper
  2. Activate Learn Mode (run the LearnFocusedFX action on your surface) - the Learn window pops up

CSI Learn Mode Window screen print

  1. Move a control on the surface
  2. Move an FXParam in Reaper with your mouse
  3. Press the Link button (once linked, this changes to an Unlink button which can sever the connection)

Tip: On some plugins, changing one parameter (e.g., Tempo Sync) may cause the focus to shift to an unwanted parameter (e.g., Rate). To work around this, press the UI button in Reaper's plugin window to temporarily toggle the GUI off. This can make it easier for Learn to focus the correct parameter.

CSI Learn Mode Link Button screen print

  1. Repeat steps 3 thru 5 as needed for additional parameters
  2. Once complete, press Save. An FX Zone file gets written to the surface's FXZones\AutoGeneratedFXZones\ folder. We recommend you keep the zone files in that folder so you can make edits in the future using Learn.

That's literally it! You should now be able to go in and activate and use your newly created fx.zon like any other.

If you want to edit the mapping after the fact, simply focus the FX again and engage Learn mode.

If you'd like to cancel at any point and start over without saving, simply close the Learn window.

If want to edit the Plugin name, as it will appear on your surface, click the Alias button.

Note: When using FX Learn Mode to assign parameters to modifiers (e.g., Shift, Option, Control, Alt), you must keep the modifier button held down after initially moving the widget.

Tip 1: The recommended approach is to quickly tap the modifier button first—this latches its state—before moving the widget you want to assign. This ensures the modifier is properly detected and applied during the learning process.

CSI Learn Mode Alias Button screen print

Once you've established a link between a Widget and a FXParam, the Edit button becomes active. Clicking Edit opens a modal window which allows you to modify the parameter alias, the number of steps (if a stepped parameter), and what the displays do. There are some more advanced features like that may not apply to all surfaces (such as color support, fonts, margins, etc.), so proceed with caution.

CSI Learn Mode Edit window

  • Parameter Alias (free form): In the top left, you can edit the Parameter Alias that will appear on your surface displays
  • Name (dropdown): The Name dropdown offers you the ability to assign the FX Parameter Name/alias to any Display Widgets defined in your FXWidgetLayout.zon
  • Value (dropdown): The Value dropdown offers you the ability to assign the FXParamNameDisplay to any Display Widgets defined in your FXWidgetLayout.zon
  • Steps (dropdown): The Steps dropdown is intended to be used for stepped parameters. Select the number of parameter steps from this list and CSI will use a predefined step values to make the parameter work. If additional editing is required, use the Params button for further refinement and/or more control
  • Ring Style (dropdown): When assigning the parameter to an encoder, you can adjust the Ring Style type here. There are options for Dot, Fill, Boost/Cut, and Spread.
  • Params (button): Opens the Advanced Parameter editing window. More on this below.
  • Done (button): Press Done to close the modal window when finished making changes.

Tip 2: On a surface with displays, if you are assigning two widgets from the same channel/cell, such as RotaryPush1 and Rotary1, CSI's Learn Mode will assign the second-mapped widget the displays. You can use the Edit window above to modify these display assignments.

Tip 3: If you need to clear a Display, click on the Display dropdown and select the blank option. Afterwards, you can reassign that display as needed or not at all.

Color and Font Options

There are some advanced Color and Font options that will only appear on-screen if your FXWidgetLayout indicates your surface supports colors and different font sizes. If not, do not indicate your surface supports these features in your FXWidgetLayout.zon. CSI cannot add this functionality where it's not supported by the hardware.

If your hardware supports these features the options are:

  • Ring Color (color picker): Sets the LED Ring color.
  • Param Name Text Color (color picker): Sets the Parameter Name font color.
  • Param Value Text Color (color picker): Sets the Parameter Value font color.
  • Indicator Color (color picker): Sets the Push indicator color.
  • Param Name Background Color (color picker): Sets the Parameter Name background color.
  • Param Value Background Color (color picker): Sets the Parameter Value background color.
  • Param Name Font (dropdown): Sets the Parameter Name font size.
  • Param Name Top/Bottom Margin (free form): Sets the top/bottom margin (in pixels) for the Parameter Name.
  • Param Value Font (dropdown): Sets the Parameter Value font size.
  • Param Value Top/Bottom Margin (free form): Sets the top/bottom margin (in pixels) for the Parameter Value.
  • Apply to All (colors): Applies the color settings to all cells on the surface (save this step prior pressing the Done button).
  • Apply to All (fonts and margins): Applies the font and margin settings to all cells on the surface (save this step prior pressing the Done button).

Advanced Parameter Editing

In the Edit window, there is an additional Params button for more advanced parameter editing (e.g. changing the Deltas of an encoder, custom step sizes, limiting parameter ranges, etc.). An overview of these features can be found in the Encoder & Parameter Customization and Stepped Parameters and Toggles pages.

Learn Mode Param Options Screen Print

  • Delta value: For use with encoders. Adjusts the encoder delta to control how much each tick changes the parameter value. For instance, you might set the step size to 0.005 (0.5%) for finer control or 0.1 (10%) for very coarse control when turning encoders.
  • Range minimum: Sets the lower limit on an FX parameter's range.
  • Range maximum: Sets the upper limit on an FX parameter's range.
  • Accelerated delta values: For creating custom acceleration curves. The number of values must match the number of acceleration steps the encoder generates. If none is entered, the Delta value gets used. Otherwise, the Accelerated delta value takes precedent.
  • Accelerated tick values: For use with acceleration and stepped parameters. The number of values must match the number of acceleration steps the encoder generates.
  • Custom Steps: Set the parameter step values. Use this when setting the number of Steps on the Edit window does not work with a given plugin.
  • OK (button): Press OK to save changes.
  • Cancel (button): Press Cancel to close this modal window without saving your changes.

Here's an example showing how those advanced Parameter values map to the text in the fx.zon files. Example of the Param syntax in a zone file

See the Stepped Parameters and Toggles as well as the Encoder & Parameter Customization for more information on these features, including syntax examples. Note: these fields only require the values followed by a space (you do not need to input commas, brackets, etc. as shown on those pages).

How to Setup/Create Zone Files for Learn

CSI's Learn feature requires some zone files setup to provide instructions as to how your surface behaves and how you'd like the mappings to work by default. CSI Support Files for the included surfaces should include the appropriate zone files already, however, if you're setting up a different surface or want to edit the mappings/behavior, you should keep reading.

Inside your CSI/Surfaces/[SurfaceName]/Zones/ folder, create a LearnZones sub-folder.

LearnZones Folder Example Screen Print

In this folder, the following files are required at a minimum:

  • FXRowLayout.zon
  • FXWidgetLayout.zon

Optional files:

  • FXPrologue.zon
  • FXEpilogue.zon

Additionally, ensure the CSI/Surfaces/[SurfaceName]/FXZones/ folder exists, with an AutoGeneratedFXZones sub-folder.

FXZones - AutoGeneratedFXZones folders

FXWidgetLayout Zone

A FXWidgetLayout zone file is the first requirement for Learn mode. This zone type dictates the available widgets for FX mapping as well as their capabilities.

Let's begin with a typical SurfaceFXLayout for an MCU-style device with Rotary, Rotary Push, and Fader widgets along with 2 displays.

Zone FXWidgetLayout
	Rotary FXParam 
	DisplayUpper FixedTextDisplay
	DisplayLower FXParamValueDisplay
ZoneEnd

#WidgetType Fader
#WidgetType RotaryPush
#WidgetType Rotary
#DisplayRow DisplayUpper
#DisplayRow DisplayLower
#RingStyle Dot
#RingStyle Fill
#RingStyle BoostCut
#RingStyle Spread
#SupportsColor

After the ZoneEnd in the FXWidgetLayout, you must define the widgets you want to make available for Learn from your Surface.txt file.

  • #WidgetType: Used to add surface controls to Learn.
  • #DisplayRow: Adds displays, which can be reassigned in the Edit window.
  • #RingStyle: Defines the available options for LED encoder rings.
  • #SupportsColor: Indicates if the surface has color support.
  • #DisplayFont: Specifies font size options if your surface supports them (example shown below).

Additionally, where supported, you can define default colors, RingStyles, and even margins. The options defined in this section will dictate the choices displayed in the Learn Mode's "Edit" window. Note: not all surfaces will support advanced features like colors, fonts, and margins.

Below is an example configuration (from the SCE-24, illustrating advanced features):

Zone FXWidgetLayout
	Rotary FXParam  
	Display1 FixedTextDisplay
	Display2 FXParamValueDisplay 
ZoneEnd

#WidgetType Rotary RingStyle=Dot LEDRingColor=#0000ffff
#WidgetType RotaryPush PushColor=#003f00ff
#DisplayRow Display1 TopMargin=0  BottomMargin=31 Font=3 TextColor=#ffff00ff BackgroundColor=#000000ff
#DisplayRow Display2 TopMargin=32 BottomMargin=63 Font=5 TextColor=#ffff00ff BackgroundColor=#000000ff
#DisplayRow Display3 TopMargin=0  BottomMargin=31 Font=3 TextColor=#00ffffff BackgroundColor=#000000ff
#DisplayRow Display4 TopMargin=32 BottomMargin=63 Font=5 TextColor=#00ffffff BackgroundColor=#000000ff
#RingStyle Dot
#RingStyle Fill
#RingStyle BoostCut
#RingStyle Spread
#DisplayFont 0
#DisplayFont 1
#DisplayFont 2
#DisplayFont 3
#DisplayFont 4
#DisplayFont 5
#DisplayFont 6
#DisplayFont 7
#DisplayFont 8
#DisplayFont 9

FXRowLayout Zone

The next requirement is an FXRowLayout.zon.

This provides a second set of instructions to CSI about which modifier mappings to allow (if any), how many cell-rows the surface has (example: the Mackie C4 has 4 rows: A, B, C, D), and how many channels.

In the FXRowLayout examples shown below, the first set of quotes in each line represents the modifiers you want to use in the zone files (first block has empty quotes to represent: unmodified). The second set of quotes in each line represents the A, B, C widget rows, if any, such as would be found on a Mackie C4 or some MIDI Fighter Twister configurations.

Here is what an FXRowLayout zone for an MCU-style surface would look like. This file uses Shift, Option, Control, Alt, Shift+Option, Shift+Control, Shift+Alt, etc. modifier combinations allowing for a very large number of FXParams to be assigned.

Zone FXRowLayout
     "" ""
     "Shift" ""
     "Option" ""
     "Control" ""
     "Alt" ""
     "Shift+Option" ""
     "Shift+Control" ""
     "Shift+Alt" ""
     "Shift+Option+Control" ""
     "Shit+Option+Control+Alt" ""
     "Shift+Control+Alt" ""
     "Shift+Option+Alt" ""
     "Option+Control" ""
     "Option+Alt" ""
     "Option+Control+Alt" ""
     "Control+Alt" ""
ZoneEnd

Here is what an FXRowLayout zone would look like for a surface with 4 rows (A, B, C, D) like the Mackie C4. Note: in the FXRowLayout zone, the A, B, C, D rows must be grouped as shown below before starting with the modified set of A, B, C, D rows. You cannot order them like: A, Shift+A, then B, Shift+B.

Zone FXRowLayout
     "" "A"
     "" "B"
     "" "C"
     "" "D"
     "Shift" "A"
     "Shift" "B"
     "Shift" "C"
     "Shift" "D"
     "Option" "A"
     "Option" "B"
     "Option" "C"
     "Option" "D"
     "Control" "A"
     "Control" "B"
     "Control" "C"
     "Control" "D"
     "Alt" "A"
     "Alt" "B"
     "Alt" "C"
     "Alt" "D"
ZoneEnd

FXPrologue Zones

FXPrologue zones are optional zones, where you can place additional, custom, CSI or Reaper actions at the start of your Learn-created FX.zon files. In the below file, activating one of these Learn-created FX zones would set the X-Touch colors to Cyan and enable the ToggleUselocalModifiers action.

Zone FXPrologue
	OnZoneActivation	SetXTouchDisplayColors Cyan
	OnZoneActivation        ToggleUseLocalModifiers
	OnZoneDeactivation	RestoreXTouchDisplayColors
	OnZoneDeactivation      ToggleUseLocalModifiers
ZoneEnd

FXEpilogue Zones

FXEpilogue zones are optional zones, where you can place additional, custom, CSI or Reaper actions at the end of your Learn-created FX.zon files. In the below file, activating one of these Learn-created FX zones would repurpose the Plugin button to clear the FX mapping from the surface via the CLearFXSlot action.

Zone FXEpilogue
     Plugin    ClearFXSlot	
ZoneEnd

Entering Learn Mode (LearnFocusedFX)

LearnFocusedFX is the CSI action needed to activate the Learn mode. You'll need to assign this to your control surface.

Zone Home
 
    Instrument    LearnFocusedFX

ZoneEnd

Learn-Generated FX.zon Example

Below is an example of a Learn-generated fx.zon for the UAD Fairchild 660 plugin. You'll notice the FXPrologue information at the top of the file, and the FXEpilogue information at the bottom.

In between, you'll see #Begin auto generated section and #End auto generated section. Do not manually modify anything you see in between those lines. The learn-generated FX.zon syntax in that section is very specific and should not be manually edited.

Zone "VST: UAD Fairchild 660 (Universal Audio, Inc.)" "Fairchild 660"
     OnZoneActivation        SetXTouchDisplayColors Cyan
     OnZoneActivation        ToggleUseLocalModifiers
     OnZoneDeactivation      RestoreXTouchDisplayColors
     OnZoneDeactivation      ToggleUseLocalModifiers
     
#Begin auto generated section

     Rotary1 FXParam 0 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (0) 0.00 0.50 1.00  ]
     RotaryPush1 NoAction 
     Fader1 NoAction 
     DisplayUpper1 FixedTextDisplay "Meter" 0 
     DisplayLower1 FXParamValueDisplay 0 

     Rotary2 FXParam 1 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (0) 0.00 0.05 0.10 0.15 0.20 0.25 0.30 0.35 0.40 0.45 0.50 0.55 0.60 0.65 0.70 0.75 0.80 0.85 0.90 0.95 1.00  ]
     RotaryPush2 NoAction 
     Fader2 NoAction 
     DisplayUpper2 FixedTextDisplay "Input" 1 
     DisplayLower2 FXParamValueDisplay 1 

     Rotary3 FXParam 2 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (10)  ]
     RotaryPush3 NoAction 
     Fader3 NoAction 
     DisplayUpper3 FixedTextDisplay "Thresh" 2 
     DisplayLower3 FXParamValueDisplay 2 

     Rotary4 FXParam 3 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (0) 0.00 0.20 0.40 0.60 0.80 1.00  ]
     RotaryPush4 NoAction 
     Fader4 NoAction 
     DisplayUpper4 FixedTextDisplay "Time Const" 3 
     DisplayLower4 FXParamValueDisplay 3 

     Rotary5 FXParam 4 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (10)  ]
     RotaryPush5 NoAction 
     Fader5 NoAction 
     DisplayUpper5 FixedTextDisplay "SC Filt" 4 
     DisplayLower5 FXParamValueDisplay 4 

     Rotary6 FXParam 5 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (10)  ]
     RotaryPush6 NoAction 
     Fader6 NoAction 
     DisplayUpper6 FixedTextDisplay "Bal" 5 
     DisplayLower6 FXParamValueDisplay 5 

     Rotary7 FXParam 6 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (10)  ]
     RotaryPush7 NoAction 
     Fader7 NoAction 
     DisplayUpper7 FixedTextDisplay "DC Thr" 6 
     DisplayLower7 FXParamValueDisplay 6 

     Rotary8 FXParam 7 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (10)  ]
     RotaryPush8 NoAction 
     Fader8 NoAction 
     DisplayUpper8 FixedTextDisplay "Output" 7 
     DisplayLower8 FXParamValueDisplay 7 



     Shift+Rotary1 FXParam 8 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (10)  ]
     Shift+RotaryPush1 NoAction 
     Shift+Fader1 NoAction 
     Shift+DisplayUpper1 FixedTextDisplay "Mix" 8 
     Shift+DisplayLower1 FXParamValueDisplay 8 

     Shift+Rotary2 FXParam 9 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (0) 0.00 0.17 0.33 0.50 0.67 0.83 1.00  ]
     Shift+RotaryPush2 NoAction 
     Shift+Fader2 NoAction 
     Shift+DisplayUpper2 FixedTextDisplay "Headroom" 9 
     Shift+DisplayLower2 FXParamValueDisplay 9 

     Shift+Rotary3 FXParam 10 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (0) 0.00 1.00  ]
     Shift+RotaryPush3 NoAction 
     Shift+Fader3 NoAction 
     Shift+DisplayUpper3 FixedTextDisplay "Power" 10 
     Shift+DisplayLower3 FXParamValueDisplay 10 

     Shift+Rotary4 FXParam 11 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (0) 0.00 1.00  ]
     Shift+RotaryPush4 NoAction 
     Shift+Fader4 NoAction 
     Shift+DisplayUpper4 FixedTextDisplay "Bypass" 11 
     Shift+DisplayLower4 FXParamValueDisplay 11 

     Shift+Rotary5 FXParam 12 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (10)  ]
     Shift+RotaryPush5 NoAction 
     Shift+Fader5 NoAction 
     Shift+DisplayUpper5 FixedTextDisplay "Wet" 12 
     Shift+DisplayLower5 FXParamValueDisplay 12 

     Shift+Rotary6 FXParam 13 RingStyle=Dot [ 0.00>1.00 (0.00,0.00,0.00,0.00,0.01,0.04,0.08) (0) 0.00 1.00  ]
     Shift+RotaryPush6 NoAction 
     Shift+Fader6 NoAction 
     Shift+DisplayUpper6 FixedTextDisplay "Delta" 13 
     Shift+DisplayLower6 FXParamValueDisplay 13 

     Shift+Rotary7 NoAction 
     Shift+RotaryPush7 NoAction 
     Shift+Fader7 NoAction 
     Shift+DisplayUpper7 NoAction 
     Shift+DisplayLower7 NoAction 

     Shift+Rotary8 NoAction 
     Shift+RotaryPush8 NoAction 
     Shift+Fader8 NoAction 
     Shift+DisplayUpper8 NoAction 
     Shift+DisplayLower8 NoAction 

#End auto generated section

     Plugin    ClearFXSlot

ZoneEnd