Track Zones - FunkybotsEvilTwin/CSIUserGuide GitHub Wiki

Track Zones

Overview of Track Zones

CSI supports four types of Track Zones, each designed to handle different workflows and surface configurations in Reaper:

  • Track
  • SelectedTrack
  • SelectedTracks
  • MasterTrack

Track

The Track zone is tailored for multi-channel surfaces, providing control over individual tracks in Reaper. Common functions include volume, pan, mute, solo, and more. Track visibility can be synchronized with either the Track Control Panel (TCP) or the Mixer Control Panel (MCP).

SelectedTrack

The SelectedTrack zone is ideal for 1-channel surfaces such as the X-Touch One or Faderport. It focuses the surface's control on the track currently selected in Reaper, making it easy to manage one track at a time.

SelectedTracks

The SelectedTracks zone is designed for multi-channel surfaces and allows dynamic interaction with selected tracks in Reaper.
Example: If you want to control only 4 drum tracks, you can enter the SelectedTracks zone and select those tracks in Reaper. These tracks will be displayed on the surface, while all others remain hidden.

MasterTrack

As the name implies, this type of zone controls the master track in Reaper.

Activating a Track Zone

The method for activating a Track Zone typically depends on the type of surface you are using:

Multi-Channel Surfaces

For multi-channel surfaces like the MCU or X-Touch, the Track zone is typically included as an IncludedZone within the Home.zon. The SelectedTracks zone can be assigned to a GoZone action, allowing you to activate it when needed.

Zone Home
    IncludedZones
       Track
    IncludedZonesEnd

    Track    GoZone SelectedTracks

Single-Channel Surfaces

For single-channel surfaces, such as the X-Touch One, the SelectedTrack zone is usually included as part of the Home.zon. This ensures the surface always controls the currently selected track in Reaper.

Zone Home
     IncludedZones
          "SelectedTrack"
     IncludedZonesEnd

For more details on zone activation, refer to the Zones documentation.

Track Zone Example

Here is a typical Track zone example.

Zone Track

    VUMeter|                     TrackOutputMeterMaxPeakLR
    DisplayUpper|                TrackNameDisplay
    Fader|                       TrackVolume
    Touch+DisplayLower|          TrackVolumeDisplay
    Flip+Fader|                  TrackPan 
					        
    Rotary|                      TrackPanAutoLeft  RingStyle=Dot   // Pan
    Toggle+Rotary|               TrackPanAutoRight RingStyle=Dot  // Width
    DisplayLower|                TrackPanAutoLeftDisplay
    Toggle+DisplayLower|         TrackPanAutoRightDisplay
					        
    RotaryPush|                  ToggleChannel
    Control+RotaryPush|          TrackPan [ 0.5 ]
    Option+RotaryPush|           TrackPanWidth [ 1.0 ]
					        
    RecordArm|                   TrackRecordArm
    Option+RecordArm|            CycleTrackAutoMode
    Option+DisplayLower|         TrackAutoModeDisplay
    Control+RecordArm|           TrackInvertPolarity
    Control+DisplayLower|        TrackInvertPolarityDisplay
					        
					        
    Alt+Option+RotaryPush|       CycleTrackInputMonitor
    Alt+Option+DisplayLower|     TrackInputMonitorDisplay
    Alt+Control+DisplayLower|    TrackRecordInputDisplay
					        
    Solo|                        TrackSolo
    Mute|                        TrackMute
    Select|                      TrackUniqueSelect
    Shift+Select|                TrackRangeSelect
    Control+Select|              TrackSelect    
ZoneEnd

Track Colors

Some widgets (such as the "Select" buttons on the Faderport8 and Faderport16 or an OSC surface designed to receive track track colors) & surfaces (like the X-Touch) work with CSI in such a way that the surface can follow the track colors in Reaper. If you have a supported device, the syntax is the word "Track" within some curly brackets (leave a space before and after).

Here is how that's handled on an X-Touch

Zone Track
    DisplayUpper|    TrackNameDisplay { Track }

Here's an example of how to get the Select buttons to light up on the Presonus Faderport8/16 using CSI:

Zone Track
    Select|     TrackUniqueSelect  { "Track" }
ZoneEnd

SelectedTracks Zone Example

Here is an example of a typical SelectedTracksZone. Notice it's pretty much identical except we're redefining the banking actions that typically live in the home.zon.

Zone SelectedTracks

    VUMeter|                     TrackOutputMeterMaxPeakLR
    DisplayUpper|                TrackNameDisplay
    Fader|                       TrackVolume
    Touch+DisplayLower|          TrackVolumeDisplay
    Flip+Fader|                  TrackPan 
					        
    Rotary|                      TrackPanAutoLeft  RingStyle=Dot   // Pan
    Toggle+Rotary|               TrackPanAutoRight RingStyle=Dot  // Width
    DisplayLower|                TrackPanAutoLeftDisplay
    Toggle+DisplayLower|         TrackPanAutoRightDisplay
					        
    RotaryPush|                  ToggleChannel
    Control+RotaryPush|          TrackPan [ 0.5 ]
    Option+RotaryPush|           TrackPanWidth [ 1.0 ]
					        
    RecordArm|                   TrackRecordArm
    Option+RecordArm|            CycleTrackAutoMode
    Option+DisplayLower|         TrackAutoModeDisplay
    Control+RecordArm|           TrackInvertPolarity
    Control+DisplayLower|        TrackInvertPolarityDisplay
					        
					        
    Alt+Option+RotaryPush|       CycleTrackInputMonitor
    Alt+Option+DisplayLower|     TrackInputMonitorDisplay
    Alt+Control+DisplayLower|    TrackRecordInputDisplay
					        
    Solo|                        TrackSolo
    Mute|                        TrackMute
    Select|                      TrackUniqueSelect
    Shift+Select|                TrackRangeSelect
    Control+Select|              TrackSelect    

    BankLeft                    Bank SelectedTracks -8
    BankRight                   Bank SelectedTracks 8
    ChannelLeft                 Bank SelectedTracks -1
    ChannelRight                Bank SelectedTracks 1
ZoneEnd

SelectedTrack Zone Example

In this SelectedTrackZone example, the track actions are hard-coded to the first channel.

Zone SelectedTrack
     DisplayUpper1                  TrackNameDisplay
     Fader1Touch+DisplayLower1      TrackVolumeDisplay
     DisplayLower1                  TrackPanAutoLeftDisplay
     Toggle+DisplayLower1           TrackPanAutoRightDisplay
     Shift+DisplayLower1            TrackAutoModeDisplay
     Option+DisplayLower1           TrackInputMonitorDisplay    
     VUMeter1                       TrackOutputMeterMaxPeakLR
     Fader1                         TrackVolume 
     Flip+Fader1                    TrackPan 
     Rotary1                        TrackPanAutoLeft RingStyle=Dot
     Toggle+Rotary1                 TrackPanAutoRight RingStyle=Dot
     RotaryPush1                    ToggleChannel
     Shift+RotaryPush1              TrackPan [ 0.5 ]
     Shift+RotaryPush1              TrackPanL [ 0.0 ]
     Option+RotaryPush1             TrackPanWidth [ 1.0 ]
     Option+RotaryPush1             TrackPanR [ 1.0 ]
     RecordArm1                     TrackRecordArm
     Shift+RecordArm1               CycleTrackAutoMode  
     Option+RecordArm1              CycleTrackInputMonitor
     Solo1                          TrackSolo
     Shift+Solo                     ClearAllSolo
     Mute1                          TrackMute
     Option+Mute1                   TrackInvertPolarity	
     Select1                        TrackUniqueSelect
     Hold+Select1                   TrackVolume [ 0.760 ]
ZoneEnd

MasterTrack Zone Example

In a typical MCU-style device, the master track is simple a fader with no display, pan knob, or must/solo buttons. As a result, typical MasterTrack zones look like this.

Zone MasterTrack
    MasterFader TrackVolume
ZoneEnd

Track Actions

The following CSI actions are available for controlling Reaper's track controls. They will receive their context from the Zone Type, whether a "Track" zone (used for controlling multiple channels) or "SelectedTrack" zone.

TrackVolume, TrackVolumeDisplay

TrackVolume is the most commonly used CSI action for controlling TrackVolume. Use this for surfaces with motorized faders or encoders. TrackVolumeDisplay will display the fader volume on your surface. The example shown below shows the syntax for TrackVolumeDisplay could be used with touch sensitive faders to only show the track volume when touching the faders (you could show the Pan level in that display the rest of the time).

Zone Track
    Touch+DisplayLower|     TrackVolumeDisplay
    Fader|                        TrackVolume
ZoneEnd

If you only wanted to see the TrackVolume on the lower display at all times, you could just remove the Touch portion and have this.

Zone Track
    DisplayLower|     TrackVolumeDisplay
    Fader|            TrackVolume
ZoneEnd

SoftTakeover7BitTrackVolume

If you are assigning TrackVolume to a 7-Bit MIDI fader or an absolute rotary [a knob with defined start and end positions] you can consider using CSI's SoftTakeover7BitTrackVolume in lieu of TrackVolume in order to avoid volume jumps when you move a fader. The "soft takeover" variant will only change the volume once the fader/knob's value passes through the current value in Reaper.

Zone Track
     Fader|      SoftTakeover7BitTrackVolume
ZoneEnd

SoftTakeover14BitTrackVolume

Same as SoftTakeover7BitTrackVolume, only designed for 14-bit MIDI faders/knobs.

Zone Track
     Fader|      SoftTakeover14BitTrackVolume
ZoneEnd

TrackPanAutoLeft, TrackPanAutoRight, TrackPanAutoLeftDisplay, TrackPanAutoRightDisplay

TrackPanAutoLeft will control TrackPan or TrackPanL (if using Dual Pans). TrackPanAutoRight will control TrackPanWidth or TrackPanR (if using Dual Pans). This adds considerable convenience in that you can use Stereo Balance Pans or Dual Pans even in the same Reaper project and control them in CSI without having to change zones. The one difference is that the WidgetMode for TrackPanAutoRight must be fixed (i.e. you can't use the Spread mode for PanWidth and Dot mode for PanR - you have to pick one). Note: in the below example, the ToggleChannel action is being used to flip between TrackPanAutoLeft and TrackPanAutoRight on the same widgets without changing zones.

Zone Track
    RotaryPush|                 ToggleChannel

    Rotary|                     TrackPanAutoLeft
    Rotary|			WidgetMode Dot
    Toggle+Rotary|              TrackPanAutoRight
    Toggle+Rotary|		WidgetMode Dot

    DisplayLower|      		TrackPanAutoLeftDisplay
    Toggle+DisplayLower|   	TrackPanAutoRightDisplay
ZoneEnd

Note: When using Dual Pans, TrackL and TrackR automation does not get written from a control surface. This appears to require a change to the Reaper API's.

TrackPan, TrackPanDisplay

Use TrackPan for controlling the TrackPan in Reaper. TrackPanDisplay will display the value of the TrackPan action on your surface.

Zone Track
     DisplayLower|      TrackPanDisplay
     Rotary|            TrackPan 0
ZoneEnd

Now, notice the number after TrackPan...The numbers are for the LED ring displays on the MCU style encoders:

  • 0 means a single led -- perfect for Pan
  • 1 means fill from right edge - centre single -- fill to left edge perfect for Width or EQ boost/cut
  • 2 - left right fill -- good for level
  • 3 - spread -- good for Q

TrackPanWidth, TrackPanWidthDisplay

TrackPanWidth is used for controlling the PanWidth control in Reaper.

Zone Track
     Shift+DisplayLower|      TrackPanWidthDisplay
     Shift+Rotary|            TrackPanWidth 1
ZoneEnd

TrackPanL, TrackPanLeftDisplay

TrackPanL controls the Left channel's pan position when using the Dual Pan option in Reaper. Note: there is a known limitation where automation is not written when using this CSI action.

Zone Track
     Alt+DisplayLower|     TrackPanLeftDisplay
     Alt+Rotary|           TrackPanL
ZoneEnd

TrackPanR, TrackPanRightDisplay

TrackPanR controls the Right channel's pan position when using the Dual Pan option in Reaper. Note: there is a known limitation where automation is not written when using this CSI action.

Zone Track
     Control+DisplayLower|     TrackPanRightDisplay
     Control+Rotary|           TrackPanR
ZoneEnd

TrackSelect

Use this action in a Track zone context to select one of the channels in Reaper.

Zone Track
     Select|     TrackSelect
ZoneEnd

TrackUniqueSelect

This action works similar to TrackSelect, but will deselect any other previously selected tracks.

Zone Track
     Shift+Select|     TrackUniqueSelect
ZoneEnd

TrackRangeSelect

Use this action to select the start and end of a range of tracks and have them all selected.

Zone Track
     Control+Select|     TrackRangeSelect
ZoneEnd

TrackSolo

TrackSolo will toggle the Solo state of the track. This action provides feedback of the solo state to the surface.

Zone Track
     Solo|     TrackSolo
ZoneEnd

TrackMute

TrackSolo will toggle the Solo state of the track. This action provides feedback of the mute state to the surface.

Zone Track
     Mute|     TrackMute
ZoneEnd

TrackRecordArm

Use TrackRecordArm to toggle the "Armed" state of the track. This action provides feedback to the surface.

Zone Track
     RecordArm|     TrackRecordArm
ZoneEnd

TrackInvertPolarity, TrackInvertPolarityDisplay

TrackInvertPolarity will invert the polarity of the track. This action provides feedback to the surface. In this example, because most surfaces do not have a dedicated button for this, I'm using the Control modifier combined with the RecordArm button to fire the action. There's also a corresponding TrackInvertPolarityDisplay action.

Zone Track
    Control+RecordArm|       TrackInvertPolarity         
    Control+DisplayLower|    TrackInvertPolarityDisplay
ZoneEnd

CycleTrackInputMonitor, TrackInputMonitorDisplay

Use CycleTrackInputMonitor to cycle through the various input monitoring modes in Reaper. TrackInputMonitorDisplay is the corresponding display action allowing you to see the current mode.

Zone Track
Option+Arm|             CycleTrackInputMonitor
Option+DisplayLower|    TrackInputMonitorDisplay

TrackNameDisplay

Use TrackNameDisplay on a display widget to show the name of the track in question. Note: if a track is not named in Reaper, it will display "Track 1", "Track 2", etc. On a surface with only 8 characters, "Track 10" may be truncated to just "Track 1". Workaround: properly name your tracks!

Here's TrackNameDisplay used in a typical "Track" zone.

Zone Track
     DisplayUpper|     TrackNameDisplay
ZoneEnd

In the below example, we've got a display widget called "MainDisplay" and want to assign the selected track's name to always appear on that widget. To do this, we can create a SelectedTrack.zon and simply add the following...

Zone SelectedTrack
     MainDisplay     TrackNameDisplay
ZoneEnd

TrackNumberDisplay

Use TrackNumberDisplay on a display widget to display the Reaper track # on your surface. In the below example, we've got a surface that has 4 display rows (FaderPort8/16, SCE-24 or an OSC device). The track number is being displayed on the second row of the display (DisplayUpperMiddle).

Zone Track
    DisplayUpper|          TrackNameDisplay
    DisplayUpperMiddle|    TrackNumberDisplay
    DisplayLowerMiddle|    TrackPanDisplay
    DisplayLower|          TrackVolumeDisplay
ZoneEnd

That's to Navelpluisje for contributing this action!

TrackOutputMeter

Use this action if your surface has two columns of meter LEDs (one for left and one for right channel). By default, CSI will display the left channel (0) on a mono meter.

Zone Track
     VUMeter|      TrackOutputMeter
ZoneEnd

If you have a surface where the meter has right and left channels, you would break those up into two widgets in your surface.txt and in your Track zone, append the channel number (0=Left, 1=Right) to the end of the TrackOutputMeter action as shown below.

Zone Track
     VUMeterLeft|      TrackOutputMeter 0
     VUMeterRight|     TrackOutputMeter 1
ZoneEnd

If you have more than just left and right channels (e.g. surround) you can use TrackOutputMeter 2, TrackOutputMeter 3, etc.

TrackOutputMeterAverageLR

Use this action if your surface has a single column LED for metering and you want that meter to show the average of both the left and right channels.

Zone Track
     VUMeter|      TrackOutputMeterAverageLR
ZoneEnd

TrackOutputMeterMaxPeakLR

Use this action if your surface has a single column LED for metering and you want that meter to show the highest peak value of both the left and right channels.

Zone Track
     VUMeter|      TrackOutputMeterMaxPeakLR
ZoneEnd

TrackVolumeWithMeterAverageLR, TrackVolumeWithMeterMaxPeakLR

These actions are designed for surfaces where you may want to repurpose LED encoder rings to function as meters when audio is playing, or track volume displays when no audio is playing. TrackVolumeWithMeterAverageLR is an average meter, whereas TrackVolumeWithMeterMaxPeakLR is a peak meter. For this to work, the LED encoder rings must be defined as their own standalone widgets.

Zone Track

    LEDRingA| TrackVolumeWithMeterAverageLR

ZoneEnd

or

Zone Track

    LEDRingA| TrackVolumeWithMeterMaxPeakLR

ZoneEnd

TrackRecordInputDisplay

The TrackRecordInputDisplay option is meant to show you which input a given channel in a track or selected track zone is set to. Examples: Mno 1 = Mono 1, 1+2 = Stereo inputs 1 and 2, MD All = MIDI All, etc.

Zone Track
    Option+DisplayLower|     TrackRecordInputDisplay    
ZoneEnd

TrackVolumeDB

TrackVolumeDB can be used for any network-based (e.g. OSC) surfaces that would expect literal db values on a fader widget.

Zone Track
    Fader|     TrackVolumeDB
ZoneEnd

TrackPanPercent, TrackPanWidthPercent, TrackPanLPercent, TrackPanRPercent

The TrackPanPercent, TrackPanWidthPercent, TrackPanLPercent, and TrackPanRPercent actions can be used for any network-based (e.g. OSC) surfaces that would expect literal pan percentage values.

Zone Track
    Fader|               TrackVolumeDB
    PanEncoder|          TrackPanPercent
    Shift+PanEncoder|    TrackPanWidthPercent
    Alt+PanEncoder|      TrackPanLPercent
    Ctrol+PanEncoder|    TrackPanRPercent  
ZoneEnd