Control Surface Settings - FunkybotsEvilTwin/CSIWiki GitHub Wiki

This page will explain how to use the CSI Control Surface Settings screen within Reaper. This screen is where you will configure your MIDI and OSC devices for use within CSI, as well as setting up some device preferences and advanced Broadcast/Listen options.

This page can be accessed via the following steps:

  1. Open Reaper
  2. Go to Preferences>Control/OSC/web
  3. If you've already setup CSI, you should see an option for Control Surface Integrator, highlight this row. If you have not setup CSI, please see the Installation and Setup page first.
  4. Click the Edit button. The below window should appear (Note: your surface setup will differ).

CSI Preferences Screen Print

Use the links below to jump to a specific topic on this page.

Surfaces

The Surfaces section on the left is where you will add MIDI and OSC surfaces to your CSI setup. This is where you will define the MIDI ports, and/or OSC IP address and ports. Before adding any surfaces, be sure to have at least one Page under the Pages section.

  • Add MIDI - click this button to add a MIDI or MCU surface.
  • Add OSC - click this button to add an OSC device (can be a phone, tablet, or even the local PC)
  • Edit - With a surface selected, click Edit to make changes to the surface
  • Remove - With a surface selected, click Remove to remove the surface from CSI

MIDI Surface Settings

When you Add or Edit a MIDI surface, the below window will appear. Note: in order for CSI to access your device's MIDI ports, the device's in and out ports must be disabled in Reaper's Preferences>MIDI Devices. Add MIDI Device Screen Print

  • Name - enter a name for your MIDI device as you want it to appear within CSI.
  • MIDI In - select the MIDI in port for your device.
  • MIDI Out - select the MIDI out port for your device.

OSC Surface Settings

When you Add or Edit an OSC surface, the below window will appear. Add OSC Device Screen print

  • Name - enter a name for your MIDI device as you want it to appear within CSI.
  • Remote device IP - enter the IP address for your OSC device. This can be a phone, tablet, or even the local PC's IP address in the case of running TouchOSC on the same laptop or PC as Reaper.
  • CSI receives on port - enter the port number that CSI should be listening for OSC messages on. This must match the port number that the OSC surface is sending on.
  • CSI sends on port - enter the port number that CSI should be sending OSC messages to. This must match the port number that the OSC surface is receiving on.

If you have a problem with two-way communication between CSI and your OSC device, ensure that you've got the IP address set correctly in both CSI and the OSC device and you've got your send/receive ports setup correctly on both as well. If everything is setup correctly, you may need to try different receive and send ports on both devices.

Pages

In CSI, a Page is the highest level of the hierarchy - with each Page containing one or more surfaces, and each surface having an .mst (if MIDI/MCU) or .ost (if OSC) file which describes the surface properties as well as a zone folder defining what exactly that surface will do in Reaper. CSI requires that at least one page exist (called "HomePage" by default) before surfaces can be added.

But CSI also allows you to create multiple Pages, with each Page containing the configuration information for whatever Surfaces and Actions you want CSI to recognize. Only one Page can be active in Reaper at any time, but you can switch between Pages easily and instantaneously similar to activating a zone.

Pages allow you to have....

  • Different surfaces enabled/disabled depending on what you're doing - i.e. different surfaces enabled on each Page
  • Different actions assigned to your surface depending on what your doing - i.e. different zone folders for one or more surfaces on each Page
  • Surface capabilities defined differently on each page - i.e. different .mst and/or files for one or more on each Page

Note: The current Page is saved within your Reaper project. Example: if you save a project while CSI is on your "MixPage", upon reopening said project, CSI will start out on your "MixPage" instead of the default "HomePage".

  • Add - click this button to add a new page. You are required to have at least one page in CSI, typically a Homepage.
  • Edit - click this button to edit the Page settings (more on these below) for the selected page
  • Remove - with a Page selected, click Remove to remove the page from CSI

Page Settings

Clicking the Add or Edit buttons, opens the page settings dialog. CSI Settings Add Page Image

  • Page Name - this is where you would edit the name of the page
  • CSI Follows Track Manager Show/Hide - select MCP if you want CSI to follow the track visibility based on Reaper's Mixer Control Panel (MCP). Select TCP if you want CSI to follow the track visibility of the Track Control Panel (TCP)
  • Bank with Other Surfaces - check this box if you'd like banking to impact all pages.
  • Ensure Selected Track Visible in Both CSI and Reaper - this option will keep the selected track visible on both the surface and Reaper. Leaving this unchecked, the CSI will not automatically bank your surface to the selected track.
  • Surface and Reaper Mixer Scroll Together - If you would like Reaper and your Control Surface to scroll together, select this option. However, it's important to note that if there are more tracks visible on screen than you have surface channels for, you may not be able to bank your surface to all tracks. For this reason, I'd suggest keeping this off by default.

CSI's included support files should already have a page called "HomePage" created for you to make first-time setup easy. If not there, as a best practice, your first page should be called "HomePage" (if anything just for consistency). Any pages you create beyond that can be named whatever you'd like.

Now you can begin adding surfaces (Add MIDI or Add OSC buttons) and selecting which .mst/.osc and Zone folder each Page will utilize. Remember: you can use completely different .mst files and/or Zone folders for each Page, completely changing how each surface will work on each Page.

See Installation for instructions on how to setup a surface.

The last thing needed for Pages to work are the required Navigation Actions on your surface to change between Pages in CSI.

Assignments

The Assignments section of the Control Surface Settings window is where you select which surface will appear on each Page, and which set of .mst and .zon files they will use on that Page.

  • Add - click this button to add a new surface to the selected Page.
  • Edit - with a surface selected, click this button to Edit that surface.
  • Remove - with a surface selected, click this button to Edit that surface.

Surface Assignment Screen

When you Add a new surface to the selected Page via the Assignment section, the below window will appear. CSI Surface Assignment Page Image

  • Surface Selector - select from the available surfaces using this dropdown.
  • Number of Channels - enter the number of channels on your surface (example: an MCU is an 8-channel surface, and X-Touch One is a 1-channel surface)
  • Channel Start Position - when using multiple surfaces, this value is used to allow CSI to span more than one surface. For a single surface setup, or a setup where you don't want CSI to span multiple surfaces, keep this value at 0. In a setup such as an MCU and an Extender, the surface on the left would have a Channel Start Position of 0, while the surface to the right have a value of 8.
  • Surface - select the .mst/.ost file for the surface you want used on this Page.
  • Zone Folder - select the zone folder for the surface you want used on this Page.
  • FXZone Folder - CSI allows you to have a common FX Zone Folder that can be shared across multiple surfaces. If this doesn't apply to your setup, simply use the same surface Zone folder you setup above. However, if you'd like to have multiple surfaces sharing an FX Zone folder, you would need to have a standalone folder within your CSI\Zones\ folder for the FX. You would select that option here when setting up the various devices that will point to that folder.

Advanced Settings (Broadcast and Listen)

The Advanced button on the Control Surface Settings screen contains features for dictating how multiple surfaces talk to each other and behave within CSI. Each surface can be set to "Broadcast" specific commands to other surfaces, and each surface can be set to listen to some or all of those broadcasted commands.

By default, surfaces in CSI operate at the page level. When you designate a Surface a Broadcaster, it Broadcasts everything, all the time, to all of its Listeners (including itself, if it is in the Listeners Surface list). And it's important to note that once a surface is setup as a "Broadcaster", it stops listening to itself unless specifically told to. This is intentional and designed for one surface to fire off commands to other surfaces, without executing that command/action itself.

Clicking the Advanced button opens the below window: CSI Broadcast and Listen Setup Screen

  • Broadcasters - Broadcasters are surfaces which will send commands to other surfaces. Use this dropdown to select the surface you'd like to define as a Broadcaster, then click the Add button to add it to the list. With a Broadcaster selected, the Remove button will remove it from the list.

  • Listeners - Listeners are surfaces which have been designated to receive commands from Broadcasters. Use this dropdown to select the surface you'd like to define as a Listener, then click the Add button to add it to the list. With a Listener selected, the Remove button will remove it from the list.

  • "Listens to" - with a Listener surface selected, the various checkboxes here will define what the listener does in response to actions/commands from any Broadcast surfaces.

Listen To Checkbox Options

  • GoHome - the Listener will respond to GoHome actions from the Broadcaster surface(s).
  • SelectedTrackSends - the Listener will respond to the GoAssociatedZone SelectedTrackSend action.
  • SelectedTrackReceives - the Listener will respond to the GoAssociatedZone SelectedTrackReceive action.
  • Custom - the Listener will respond to the GoAssociatedZone Custom action.
  • Learn - the Listener will respond to the GoAssociatedZone LearnFXParams action.
  • AutoMap - the Listener will respond to the AutoMapFX action.
  • FXMenu - the Listener will respond to the GoAssociatedZone SelectedTrackFXMenu and GoFXSlot actions.
  • LocalFXSlot - the Listener will only respond to local mapping of the GoFXSlot action. Use this if you want to have two different FX mapped on the same surfaces, but otherwise broadcasting/lsitening to one another.
  • SelectedTrackFX - the Listener will respond to the GoAssociatedZone SelectedTrackFX action.
  • FocusedFX - the Listener will map FocusedFX based on the broadcast surface.
  • FocusedFXParam - the Listener will map FocusedFXParam based on the broadcaster.
  • Modifiers - the Listener will respond to Modifiers set on the broadcast surface.

If you wanted two or more surfaces to mirror each other and act as a single unit, you would need to add all surfaces as broadcasters AND listeners, making sure they were all listening to the same checkbox items from the list above.

CSI.ini

All of the Page, Surface, Assignment, and Broadcast/Listen settings are ultimately stored in a file called csi.ini stored within the CSI sub-folder inside the Reaper Resource Path. The CSI.ini gets created when you setup CSI for the first time and shouldn't require direct user editing, however, if you want to understand how the csi.ini works, or need to troubleshoot, read on!

Below is an example CSI.ini.

Version 3.0

MidiSurface "X-Touch" 25 26 
MidiSurface "X-TouchOne" 7 9 
MidiSurface "MFTwister" 6 8 
OSCSurface "iPad" 8008 9008 192.168.1.160
OSCSurface "Desktop" 8011 9011 192.168.1.152
OSCSurface "iPhone" 9009 8009 192.168.1.153

Page "HomePage" UseScrollLink
	"X-Touch" 8 0 "X-Touch.mst" "X-Touch" "X-Touch" 
	"X-TouchOne" 1 0 "X-Touch_One.mst" "X-TouchOne" "X-TouchOne" 
	"MFTwister" 8 0 "MIDIFighterTwisterEncoder.mst" "FXTwister_MFT" "FXTwisterFXZones" 
	"iPad" 8 0 "FXTwister.ost" "FXTwister_iPAD" "FXTwisterFXZones" 
	"Desktop" 8 0 "FXTwister.ost" "FXTwister_Desktop" "FXTwisterFXZones" 
	"iPhone" 1 0 "CSIPhoneRemote.ost" "CSIPhoneRemote" "CSIPhoneRemote" 

	Broadcaster "MFTwister"
		Listener "MFTwister" "GoHome FocusedFX Learn AutoMap FXMenu "
		Listener "iPad" "GoHome FocusedFX Learn AutoMap FXMenu "
		Listener "Desktop" "GoHome FocusedFX Learn AutoMap FXMenu "

	Broadcaster "iPad"
		Listener "MFTwister" "GoHome FocusedFX Learn AutoMap FXMenu "
		Listener "iPad" "GoHome Learn AutoMap "
		Listener "Desktop" "GoHome Learn AutoMap "

	Broadcaster "Desktop"
		Listener "MFTwister" "GoHome FocusedFX Learn AutoMap FXMenu "
		Listener "iPad" "GoHome Learn AutoMap "
		Listener "Desktop" "GoHome Learn AutoMap "

The CSI version number is included in the first row. If missing, CSI will throw up an error when Reaper starts.

Next, you see...

MidiSurface "X-Touch" 12 11

This tells CSI that the user has configured a MIDI surface, named this device "X-Touch", and that device uses MIDI port 12 for incoming messages and MIDI port 11 for outbound messages.

There's also an OSC device in this setup.

OSCSurface "iPad" 8008 9008 192.168.1.160

This is telling CSI that there is an OSC surface that the user has named "iPad Pro", and that receives on port 8000, transmits to port 9000, and that iPad Pro has an IP Address of 10.0.0.146.

Next, each Page in CSI is defined, with the surfaces, .mst file, and zone folder that will be used for each page.

Page "HomePage" 
"X-Touch" 8 0 "X-Touch.mst" "X-Touch" "X-Touch" 
"MFTwister" 8 0 "MIDIFighterTwisterEncoder.mst" "FXTwister_MFT" "FXTwisterFXZones" 
"iPad" 8 0 "FXTwister.ost" "FXTwister_iPAD" "FXTwisterFXZones" 

Page "HomePage"

...is the name of the page.

"X-Touch" 8 0 "X-Touch.mst" "X-Touch" "X-Touch" 
"MFTwister" 8 0 "MIDIFighterTwisterEncoder.mst" "FXTwister_MFT" "FXTwisterFXZones" 
"iPad" 8 0 "FXTwister.ost" "FXTwister_iPAD" "FXTwisterFXZones"

This says the X-Touch surface gets included in the HomePage, has 8 channels, a channel offset of 0, and uses the X-Touch.mst and "X-Touch" zone folder. The MFTwister and iPad definitions follow the same format but you'll notice they use a shared FXZone folder called "FXTwisterFXZones"

If you had multiple pages defined, they would follow this same format as shown here...

Version 3.0

MidiSurface "XTouchOne" 7 9
MidiSurface "MFTwister" 6 8 
OSCSurface "iPad Pro" 8003 9003 10.0.0.146 

Page "HomePage" 
"XTouchOne" 1 0 "X-Touch_One.mst" "X-Touch_One_SelectedTrack"
"MFTwister" 8 0 "MIDIFighterTwisterEncoder.mst" "FXTwisterMenu"
"iPad Pro" 8 0 "FXTwister.ost" "FXTwisterMenu"

Page "FocusedFXPage" 
"XTouchOne" 1 0 "X-Touch_One.mst" "X-Touch_One_SelectedTrack"
"MFTwister" 8 0 "MIDIFighterTwisterEncoder.mst" "FXTwisterFocusedFX"
"iPad Pro" 8 0 "FXTwister.ost" "FXTwisterFocusedFX"

Broadcasters and Listeners are also defined in the csi.ini as shown below. Each Broadcaster is it's own group, as shown in the top line. Immediately below this, are the listeners that belong to that Broadcast group and which of the checkbox items they are listening to.

	Broadcaster "MFTwister"
		Listener "MFTwister" "GoHome FocusedFX Learn AutoMap FXMenu "
		Listener "iPad" "GoHome FocusedFX Learn AutoMap FXMenu "
		Listener "Desktop" "GoHome FocusedFX Learn AutoMap FXMenu "

	Broadcaster "iPad"
		Listener "MFTwister" "GoHome FocusedFX Learn AutoMap FXMenu "
		Listener "iPad" "GoHome Learn AutoMap "
		Listener "Desktop" "GoHome Learn AutoMap "

	Broadcaster "Desktop"
		Listener "MFTwister" "GoHome FocusedFX Learn AutoMap FXMenu "
		Listener "iPad" "GoHome Learn AutoMap "
		Listener "Desktop" "GoHome Learn AutoMap "

Lastly, the Page Options will appear in the csi.ini as...

  • FollowTCP - By default CSI follows the track visibility of Reaper's MCP view. Use Follow TCP to override the default functionality.
  • UseScrollLink - This turns on scroll linking between the surface and Reaper (Reaper follows CSI). The default is off.
  • NoSynchPages - With this disabled, each page will have independent banking. The default is on.