Zones - FunkybotsEvilTwin/CSIWiki GitHub Wiki

Zones are where we do two things:

  • where we map the widgets defined in our mst files to the actions we want to perform when they are invoked (pressed, rotated, etc)
  • where we group multiple action/widget mappings together into related groups.

A Simple Example

The widget/action mapping part is easy. Let's say we have a widget called PlayButton, and we want it to perform the Play action when pressed, we would simply use the following syntax in our zon file.

PlayButton Play

There's obviously more options than just play. Have a look at the Action Reference page for more examples.

However, we can't just have this sitting by itself. We need to put it inside a zone definition, usually along with other widgets performing related functions (say, the Stop, Record, FF, Rewind buttons, etc). At a minimum, we’d need something like this:

Zone Home
        PlayButton Play
ZoneEnd

Provided our CSI.INI and Widget definitions are setup correctly, this should allow us to control the Play button from our Surface.

One Zone Per File

CSI requires that a single zone exist in each .zon file. For example: a typical MCU-style zone folder would be made up of multiple .zon files such as...

Home.zon
Track.zon
TrackSend.zon
TrackReceive.zon
TrackFXMenu.zon
SelectedTrackSend.zon
SelectedTrackReceive.zon
SelectedTrackFXMenu.zon
Buttons.zon
MasterTrack.zon
Marker.zon
FocusedFXParam.zon

This makes it easier to borrow other people's zones and add them to your setup. Example: if you see a SelectedTrackSendSlot.zon file that works for the X-Touch, you can just copy and paste that into your surface folder, and use that with a Mackie Universal as long as the widget names are the same.

Tip: within each \CSI\Zones[Surface] folder, it's probably a best practice to create an "FX Zones" sub-folder if you plan on mapping FX. This way, your surface zone files can all live together in the root of the folder, and all of your fx zones can exist in the \CSI\Zones[Surface]\FX Zones folder, away from the surface files. Not a requirement, but will help keep things tidy.

Associated Zones

Associated Zones are zones with a defined purpose. Where applicable, when these zones are active, they will provide feedback to the surface (i.e. a button will light up). The name of the zone must match the below list exactly, and unless specified otherwise, these must be defined in the AssociatedZone list within your home.zon.

The Associated Zone types are:

  • Home- This zone is required and is the 'starting state' for CSI
  • Buttons- This zone is generally used for assigning buttons to CSI and Reaper actions
  • Track- Used when you want to control multiple channels across multiple widgets (e.g. 8 faders assigned to 8 channels)
  • SelectedTrack- Used for controlling the selected track in Reaper (commonly used for 1 fader surfaces)
  • MasterTrack- This is for assigning the master track fader to your surface
  • MasterTrackFXMenu- This is for assigning FX on the master track. Note: there is no Reaper API which would allow CSI to access Monitor FX so these cannot currently be mapped.
  • SelectedTrackFXMenu- Used for activating FX.zon files - shows the FX slots of the selected channel
  • SelectedTrackSend- Used for controlling the various sends on the selected channel
  • SelectedTrackReceive- Used for controlling the various Receives (if any) on the selected channel
  • TrackFXMenu- Used for activating FX.zon files - shows the same FX Slot across multiple channels
  • TrackSend- Used for controlling the same Send slot across multiple channels
  • TrackReceive- Used for controlling the same Receive slot across multiple channels
  • Custom - This is a specialty AssociatedZone type allowing you to have a custom AssociatedZone. Its scope is limited to the SelectedTrack.
  • LearnFXParams- Used to enter the Learn Mode for FX
  • SelectedTrackFX- This AssociatedZone does not need to be defined in the AssociatedZone list in the Home zone. It works to enable any FX on the selected track you have a mapping for and relies on the fx.zon.

Activating Zones

Depending on the type of zone you want to activate, there are few methods to accomplish this task. If you're looking to activate one of the zone types with a fixed name, there are dedicated CSI actions for each type...

Zone you want to activiate...   ActionName...
Home                            GoHome
SelectedTrackFXMenu             GoAssociatedZone SelectedTrackFXMenu
SelectedTrackSend               GoAssociatedZone SelectedTrackSend
SelectedTrackReceive            GoAssociatedZone SelectedTrackReceive
TrackFXMenu                     GoAssociatedZone TrackFXMenu
TrackReceive                    GoAssociatedZone TrackReceive
TrackSend                       GoAssociatedZone TrackSend
MasterTrackFXMenu               GoAssociatedZone MasterTrackFXMenu
SelectedTrackTCPFX              GoAssociatedZone SelectedTrackTCPFX
SelectedTrackFX                 GoAssociatedZone SelectedTrackFX
LearnFXParams	                GoAssociatedZone LearnFXParams

Here's what that looks like in a Buttons.zon

    Track                       GoHome
    MidiTracks                  Reaper _S&M_WNCLS4          // Closes all(!) FX chain windows
    MidiTracks                  Reaper _S&M_WNCLS3          // Closes all(!) floating FX windows  
    Global+Track                GoAssociatedZone SelectedTracks			                 
    Pan                         GoAssociatedZone Folder
    Global+Pan                  GoAssociatedZone VCA	                 
    EQ                          GoAssociatedZone SelectedTrackReceive
    Global+EQ                   GoAssociatedZone TrackReceive
    Send                        GoAssociatedZone SelectedTrackSend
    Global+Send                 GoAssociatedZone TrackSend	
    Plugin                      GoAssociatedZone SelectedTrackFXMenu
    Global+Plugin               GoAssociatedZone TrackFXMenu			                 
    Instrument                  GoAssociatedZone LearnFXParams

    Inputs                      GoAssociatedZone SelectedTrackTCPFX
    AudioTracks                 GoAssociatedZone MasterTrackFXMenu

    F6                          GoAssociatedZone SelectedTrackFX

Home Zone, IncludedZones, AssociatedZones

Every surface in CSI requires a Home zone. This sets the default state for your surface via IncludedZones and AssociatedZones, which we will explain shortly. If you require one surface to sync up with, or dictate the behavior of another, you'd define the required Broadcast and Listen behavior in the Home.zon. It's also not uncommon to include actions assigned to Virtual Widgets in the Home zone to set the state of the surface when initializing the surface or "going" Home.

The types of zones defined in "IncludedZones" will dictate the starting (or "home") state of the surface. Example: it's common to have a Track zone combined with a Master Track and Buttons zone in an MCU-style surface because we want the faders, rotaries and buttons all functional and defined in a predictable way when going Home. Additionally, CSI version 2 introduced the concept of AssociatedZones. These are zones like Sends, Receives, and FX Menus that are not activated as part of the home.zon, but will be called from this zone. Example: when I activate the Send zone, I want the Sends mapped to faders and rotaries until I go Home again where they control tracks - that makes the Send zone a typical use-case for AssociatedZones. AssociatedZones behave like radio buttons, with only one being activated at a given time.

Below is an example of a typical MCU-style home.zon. The "Track" zone will use the displays and widgets when the Home zone is active, but if you want to call up an FX menu, Sends, or Receives to then takeover over some of the widgets, they need to be listed as AssociatedZones as shown below. When configured like this, the AssociatedZones function as "radio-button" style zones, where only one can be active at a given time (example: SelectedTrackSends or SelectedTrackReceives - not both simultaneously).

Zone Home
    IncludedZones
       Buttons
       Track
       MasterTrack
    IncludedZonesEnd
    AssociatedZones
       SelectedTracks
       SelectedTrackSend
       SelectedTrackReceive
       SelectedTrackFXMenu
       MasterTrackFXMenu
       TrackSend
       TrackReceive
       TrackFXMenu
       VCA
       Folder
       SelectedTrackTCPFX
       LearnFXParams
       Custom
    AssociatedZonesEnd
ZoneEnd

On the other hand, here's an example of a home.zon where the Track zone, SelectedTrackFXMenu, and SelectedTrackSend zones are all activate in the home.zon itself. For this particular device/use-case, RowA of the surface covers the Track zone, RowB covers the SelectedTrackFXMenu, and RowC covers SelectedTrackSend and I wanted all 3 active simultaneously which is why we have all 3 listed as IncludedZones in the Home.zon versus AssociatedZones in the prior example.

Zone "Home"
    IncludedZones
        "Buttons"
        "Track"
        "SelectedTrackFXMenu"
        "SelectedTrackSend"
    IncludedZonesEnd
ZoneEnd

The Home.zon would also include any Broadcast and Listen messages and is also a great place to define actions assigned to Virtual Widgets.

FX Zones

FX zone file names can be whatever you'd like them to, but the FX zone name in the .zon file itself must match the plugin name in Reaper exactly. See Manual FX Mapping for more information on how to create an FX.zon.

SubZones

SubZones are custom zones that can be called up from their parent zone. They have no fixed naming convention like the AssociatedZones. If your SubZone name includes a space, wrapping the name in quotes is required (e.g. if your zone name is "Mix Zone"), however, it's a common CSI practice to include quotes in all zone names, though technically not required.

First, the SubZones need to be defined and within the parent zone (lines 2-4 below). You also need a way to activate the SubZone using the GoSubZone action (in this case, the Zoom button). Here is one example where a "Zoom" subzone is being called from the buttons.zon:

Zone "Buttons"
    SubZones
       "Zoom"
    SubZonesEnd

    Zoom        GoSubZone "Zoom"
ZoneEnd

The SubZone itself would look like any other standalone .zon file. Below is our Zoom.zon example. Also note that once we are in one of those custom SubZones, we need a way to exit the SubZone. You may want to use the same button you used to activate the SubZone and assign that to the LeaveSubZone action in order for it to behave like a toggle.

Zone "Zoom"
     Up                      Reaper 40111     // Zoom in vertical
     Down                    Reaper 40112     // Zoom out vertical
     Left                    Reaper 1011      // Zoom out horizontal
     Right                   Reaper 1012      // Zoom in horizontal
     
     Shift+Up                Reaper 40113     // View: Toggle track zoom to maximum height
     Shift+Down              Reaper 40110     // View: Toggle track zoom to minimum height
     Shift+Left              Reaper 40295     // View: Zoom out project
     Shift+Right             Reaper 41190     // View: Set horizontal zoom to default project setting

     Zoom LeaveSubZone
ZoneEnd

If you have multiple SubZones, you can go directly from SubZone to SubZone, as long as each SubZone is contained within the same enclosing Zone. Example: you can have "Zoom", "Marker", and "Scroll" SubZones, and navigate directly from SubZone to SubZone without needing to return home.

SubZones are also commonly used in FX, for example, where a mastering suite plugin may have lots of different sections and more automation than you have on your surface. In those instances, you could create a "compressor" SubZone, and a "limiter" SubZone, etc. See FX SubZones for more information.

A Slightly More Useful Example

As great as it is to get that first action happening when you press a Surface button, let’s look at a slightly more interesting example. A common surface setup might include a Buttons.zon that has various CSI and Reaper actions that can be called up from the surface. Some of these buttons may even call other zones. Here's an excerpt of a Buttons.zon:

Zone "Buttons"
    Track                       Reaper 1156	// Toggle item grouping override
    Pan                         Reaper 1155	// Cycle ripple editing mode
    EQ                          Reaper 40070	// Move envelope points with media items
    Send                        Reaper 40145 	// Toggle Grid Lines
    Hold+Send                   Reaper 40071	// Show snap/grid settings
    Plugin                      Reaper 1157	// Toggle snapping
    Hold+Plugin			Reaper 40071	// Show snap/grid settings
    Instrument                  Reaper 1135	// Toggle locking
    Hold+Instrument		Reaper 40277	// Show lock settings
    BankLeft                    TrackBank -8
    BankRight                   TrackBank 8
    ChannelLeft                 TrackBank -1
    ChannelRight                TrackBank 1
    Flip                        Flip
    GlobalView                  GoHome
    GlobalView                  Reaper _S&M_WNCLS3        	// Close all floating FX windows
    GlobalView                  Reaper _S&M_WNCLS4        	// Close all FX chain windows
    GlobalView                  Reaper _S&M_TOGLFXCHAIN   	// Toggle FX Chain for selected tracks     
    nameValue                   NoAction   
    smpteBeats                  CycleTimeDisplayModes
    MidiTracks                  GoSelectedTrackSend
    Inputs                      GoSelectedTrackReceive
    AudioTracks                 GoSelectedTrackFXMenu
    AudioInstrument             GoTrackSend
    Aux                         GoTrackReceive
    Busses                      GoTrackFXMenu
    Outputs                     ToggleEnableFocusedFXMapping 
    User                        ToggleEnableFocusedFXParamMapping
ZoneEnd

As another example, I might define a zone called Track which collects all my track faders and related widgets into a single group, again because for me they are all related to controlling my tracks.

Zone "Track"
    DisplayUpper|               TrackNameDisplay
    Fader|Touch+DisplayLower|   TrackVolumeDisplay
    DisplayLower|               MCUTrackPanDisplay
    VUMeter|                    TrackOutputMeterMaxPeakLR
    Fader|                      TrackVolume 
    Flip+Fader|                 TrackPan 
    Rotary|                     MCUTrackPan
    RotaryPush|                 ToggleMCUTrackPanWidth
    RecordArm|                  TrackRecordArm
    Solo|                       TrackSolo
    Mute|                       TrackMute
    Select|                     TrackUniqueSelect
    Shift+Select|               TrackRangeSelect
    Control+Select|             TrackSelect
ZoneEnd

Note the | character after the name of the widgets. These will get replaced with the actual number derived from the number of channels you entered during setup. It is simply a shorthand way of reducing typing. So for example if you specified 8 channels this line:

Fader| TrackVolume

will cause this to be generated automatically by CSI...

Fader1 TrackVolume

Fader2 TrackVolume

Fader3 TrackVolume

Fader4 TrackVolume

Fader5 TrackVolume

Fader6 TrackVolume

Fader7 TrackVolume

Fader8 TrackVolume

Adding Comments to Zones

When triggering custom actions or using actions whose meanings may otherwise not be obvious, it's a good idea to add comments to your in your .zon files. CSI allows for two types of comments:

  1. / Lines that begin with a forward slash are completely ignored by CSI and are good for commenting sections of code. Hint: these also work in .mst files.
  2. // Trailing comments are preceeded by two forward slashes and can be used after an action in a .zon file

Here is an example from a .zon file that uses both types of comments.

Zone "Buttons"

/ Using the GlobalView button to activate the Home zone and then run the actions to close the floating FX windows.
    GlobalView                  GoHome
    GlobalView                  Reaper _S&M_WNCLS3        	// Close all floating FX windows
    GlobalView                  Reaper _S&M_WNCLS4        	// Close all FX chain windows
    GlobalView                  Reaper _S&M_TOGLFXCHAIN   	// Toggle FX Chain for selected tracks