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:
- / 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.
- // 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