1. Find the Reaper resource path by running the Reaper Action: Show REAPER resource path in finder (or Windows equivalent). This is important as the folder may be different between different installs, Portable installs, etc. 2. Close Reaper. 3. Open the .zip file. The extracted folder will contain a subfolder called "CSI", which you should put in the Reaper resource path. Your CSI folder contents should look like this... CSI Folder Structure 4. Windows: Put the reaper_csurf_integrator.dll (either 32 or 64 bit according to your Reaper installation) in the folder named UserPlugins in the Reaper resource path. Mac: put the .dylib file in the same UserPlugins folder (requires Mac OS 10.12 or later). 5. Start Reaper. 6. In Reaper go to Options>Preferences (or just Ctrl+P) (a new window will appear). 7. Scroll down to the bottom and click on Control/OSC/web. 8. In the window click on "Add" (a new window will open). 9. Click on the empty dropdown beside "control surface mode" and select Control Surface Integrator - this will now show the settings for CSI. If Control Surface Integrator is not visible, you might have to install the Microsoft Visual C++ 2019 runtime 32bit | 64bit and restart Reaper. 10. There is a default Page ("HomePage") already defined to get you started. 11. Click "Add Midi", "Add OSC", or "Add EuCon". -- see more detailed instructions for EuCon below. 12. Enter the number of channels on your surface -- e.g. MCU has 8 channels 13. Enter the number of Sends you would like to display -- must be no more than number of channels -- e.g. for MCU 8 Sends is maximum. 14. Enter the number of FX Menu choices you would like to display -- must be no more than number of channels -- e.g. for MCU 8 FX Menu choices is maximum. 15. Select your midi in and midi out ports (however you have your surface plugged into your computer), or your Remote IP, OSC in port, and OSC out port (however your OSC device is configured). Start any OSC device apps now. 16. Choose an mst template for your Midi surface or an OSC template for your OSC surface. 17. Choose the folder where your Zone files are located, CSI will attempt to guess based on your mst/osc choice, but you can override this. 18. "OK" everything. 19. While still in Options|Preferences, if your device is MIDI, go to MIDI Devices and make sure the Surfaces you wish to use with CSI are Disabled for both Input and Output. Notes • The information entered in steps 11 through 17 are stored in CSI.ini in your CSI folder. Once you're comfortable, it's sometimes easier to edit this information directly in this file. Installing CSI Updates If you're already running a 1.x release of CSI or later and currently have a working configuration, do NOT overwrite your current CSI.ini with the one in the .zip folder when installing updates to CSI. By the same token, do not overwrite any .zon files or zone folders you may have customized as you would be replacing your customized files and going back to stock. Unless instructed otherwise, updates usually involve no more than copying over the .dll or dylib to the appropriate UserPlugins folder. As mentioned on the Installation page, the configuration of your CSI installation is ultimately stored in a file called csi.ini. Here's a typical CSI.ini: Page "HomePage" FollowMCP NoSynchPages UseScrollLink MidiSurface "Console1" 7 6 "Console1.mst" "Console1" 0 0 0 0 MidiSurface "LaunchPad" 6 7 "LaunchPadMiniMK3.mst" "LaunchPadMiniMK3" 0 0 0 0 OSCSurface "iPad" 8001 9001 "TouchOSCPad.ost" "TouchOSCPad" 0 0 0 0 192.168.2.19 OSCSurface "iPhone" 8000 9000 "TouchOSCPhone.ost" "TouchOSCPhone" 0 0 0 0 192.168.2.11 MidiSurface "A800" 10 8 "RolandA800.mst" "RolandA800" 0 0 0 0 EuConSurface "EuCon" "EuCon" 64 8 8 0 The line starting with "Page" defines a Page. From left to right, this states that: • There is a Page named "HomePage" • It follows the MCP (mixer control panel) track visibility • NoSynchPages means that this Page banks "by itself" -- if you go to another Page it will not be banked to the same location • UseScrollLink ensures that when you bank Tracks on the surface, they are made visible in the Reaper GUI All the lines that come after that, starting with MidiSurface, represent each of the control surfaces. The Channel Offset governs how the channels display. Suppose you had a Surface with 8 Faders and an Extender with 8 Faders. You could set the Surface Channel Offset to 0, and the Extender Channel Offset to 8, to get Channels 1-8 to show up on the Surface and channels 9-16 to show up on the Extender. Let's look look at one of them: MidiSurface "Console1" 7 6 "Console1.mst" "Console1" 0 0 0 0 From left to right, this states that: • There is a control surface named Console1 • It sends MIDI into Reaper on port 7 • It receives MIDI from Reaper on port 6 • The controls it contains are defined in a file called Console1.mst (see Defining Control Surface Capabilities) • The zones it contains are in a folder called Console1 under the Zones folder (see Defining Control Surface Behaviour) • 0 - Number of Channels - Console 1 has no Channels, an MCU has 8, etc. • 0 - Number of Sends - Console 1 has no Sends, an MCU has 8, etc. • 0 - Number of FX Menu Items - Console 1 has no FX Menu Items, an MCU has 8, etc. • 0 - Channel Offset -- this tells CSI how far from the left edge of the CSI virtual console you want your surface to start Overview The CSI Project aims to let you integrate your hardware control surfaces into Reaper with a much higher level of control than is possible out of the box. If you're prepared to put in the effort to customise your configuration, you should be able to integrate one or more control surfaces (Surfaces from now on) into a single virtual Surface. It supports MIDI, OSC, and EuCon. This wiki focuses on MIDI support, but OSC and EuCon are very similar, High-level Concepts Pages Within CSI you can define one or more Pages, with each Page containing the configuration information for whatever Surfaces and Actions you want CSI to recognise. Only one Page can be active in Reaper at any time, but you can switch between Pages easily. So for example, you might have a Recording Page and a Mixing Page, with the physical elements on your Surfaces (eg. buttons, faders, etc) mapped to different actions in each. You can have surfaces included, left out, or even defined completely differently on each different Page. Surfaces Each Surface within your page is represented by 2 major pieces: • mst/ost file- the Surface Template file, which specifies the Surface's capabilities. ie. what elements it contains (eg. buttons, faders, encoders, lights, displays, etc), and what MIDI/OSC messages it sends and expects to receive. • Zone file - Zone files can define a couple of different behaviours: ◦ Controlling Reaper - how the Surface elements defined in the mst/ost file are mapped to Actions ◦ Controlling Plugins - how the Surface elements defined in the mst/ost file will map to parameters in your VST plugins Defining Control Surface Capabilities GeoffAWaddington edited this page on Nov 19, 2020 · 12 revisions If we want to use one or more Control Surfaces with CSI, we need to define what capabilities they have. ie. what controls they have (eg. buttons, faders, encoders, etc), what feedback mechanisms they have (displays, lights, etc), etc. .mst files are for midi devices and are used in the following examples -- similarly, .ost files are for OSC devices -- see the CSI/Surfaces/OSC folder for OSC examples. Note, this is nothing yet to do with what should happen when those buttons, etc are clicked, we're just defining the capabilities. We define these capabilities in a file with a .mst extension. Beyond the .mst extension, the rest of the filename is up to you, but it makes sense for it to reflect the model of controller. So for a BCF2000 control surface, I'd have a BCF2000.mst file, for a Launchpad Mini, I'd probably have a LaunchpadMini.mst. Here's a snippet from one of my .mst files: Widget Rotary8 Fader7Bit b0 20 7f FB_Fader7Bit b0 20 00 Toggle 90 1f 7f WidgetEnd Widget RotaryPush8 Press 90 1f 7f WidgetEnd Widget UpperButton1 Press 90 20 7f FB_TwoState 90 20 7f 90 20 00 WidgetEnd Widget Fader1 Fader14Bit e0 7f 7f FB_Fader14Bit e0 7f 7f Touch 90 68 7f 90 68 00 WidgetEnd A few things to note: • We're defining named Widgets. A Widget very often maps to a single physical control on a Surface, however it's important to realise it doesn't have to. For example a Widget may be a combination of a button and separate LED. • Within each Widget, we define the capabilities of that widget. These could be one or more of either: ◦ Message Generators - things that will result in a message being sent to CSI. eg. Press, Fader14Bit, etc ◦ Feedback Processors - things that will receive a message back from CSI to display feedback on the surface. eg. FB_TwoState, FB_Fader14Bit, etc where the FB represents FeedBack. • Each of the Message Generators and Feedback Processors may have a varying number of parameters that follow them that define the MIDI Message details sent/received and other behaviour. Look at the specific Message Generators/Feedback Processors you are using to see what parameters it supports. So for example, my UpperButton1 Widget is defined as: Widget UpperButton1 Press 90 20 7f FB_TwoState 90 20 7f 90 20 00 WidgetEnd Which says this Widget is a combination of a: • Press MIDI Generator, which means when pressed it will send the MIDI Message 90 20 7f • and a FB_TwoState Feedback Processor, which will: ◦ receive a MIDI Message of either 90 20 7f or 90 20 00 and display that to the user. In my case, this is displayed as an LED, where 90 20 7f represents the On state and 90 20 00 represents the Off state. Whereas my RotaryPush8 widget is much simpler, using a Press Message Generator that sends only the MIDI Message 90 20 7f when it is pressed. Nothing on release, and no feedback. Widget RotaryPush8 Press 90 1f 7f WidgetEnd Note: • Because the .mst file doesn't specify anything about behaviour, just surface capabilities, in theory anyone with the same model surface should be able to reuse the same .mst file, even if they want to assign different behaviours to those controls. eg. If I have a BCF2000, and so do you, in theory we can use the same .mst file. However, be careful here as if you have changed the configuration of your surface, it may be sending different midi messages, in which case someone else's .mst file may not work for you. • It's easy to forget that you're not controlling what the surface does in your MST. It is more accurate to say you are reflecting what it does. For example, if my surface isn't currently sending a message on button release, then defining it as a Press control with a Release message in your .mst won't magically make it start. Either edit the surface (if possible) to make it do that, or define it in the .mst as a Press with a single message. Message Generators Anthony Oetzmann edited this page 4 days ago · 24 revisions Message Generators allow you to define what MIDI messages the surface sends to CSI: • Press - a simple generator that sends a single MIDI message on press, and optionally sends another message when released. Often, but not limited to, a button. • AnyPress - a variation of Press needed for some devices. • Fader7Bit - sends a MIDI message in a range specifying the current absolute value of the control. • Fader14Bit - like Fader7Bit, but has a larger (or more fine grained) set of values. • Encoders - unlike the Faders, an Encoder sends a relative value (increase/decrease) • MFTEncoder - a special encoder only found on the Midi Fighter Twister controller The general pattern here is to use the MIDI Monitor to observe what values are sent when your widget is manipulated. So for example, when I press one of the buttons on my controller I see this: The first line showed up when I pressed, the second one when I let go, so a reasonable assumption is the MIDI Generator in my Widget should be: Press 90 5d 7f 90 5d 00 That said, please read the section on Press for some guidance/recommendations. Feedback Processors allow you to define how your Widget will display feedback from CSI to the user. A simple example may be lighting up an LED to indicate the Mute/Solo state of a track. Another may be positioning a motorised fader to the correct position for Track Volume. It is important to understand how this works in practise. Let's say we have a button defined in our MST file that has an LED light to indicate its status. Widget UpperButton1 Press 90 20 7f FB_TwoState 90 20 7f 90 20 00 WidgetEnd Then in our Zone file, we bind it to our TrackMute action. UpperButton1 TrackMute Here's the best case flow of what happens when we press the button on the surface: • Press the button • The surface sends the 90 20 7f message to CSI • CSI attempts to mute the track in Reaper • CSI then queries Reaper to see if the track is currently muted (eg. if the attempt to mute it worked) • Assuming it is muted, it then sends the 90 20 7f message back to the surface, instructing it to turn the light on At some point in the future, the track becomes unmuted (either by pressing the button again as above, or through the Reaper GUI) • CSI sends the 90 20 00 message back to the surface, instructing it to turn the light off Note: • It's important to understand it's not the surface deciding when to turn the light on or off. It's doing it in response to a message from CSI. We don't want the surface managing the state of the buttons, that responsibility belongs to Reaper/CSI. Included Feedback Processors • FB_TwoState • FB_ Fader14Bit • FB_ Fader7Bit • FB_ Encoder • FB_VUMeter • FB_GainReductionMeter • FB_QConProXMasterVUMeter • FB_MCUTimeDisplay • FB_MCUVUMeter • FB_MCUDisplayUpper • FB_MCUDisplayLower • FB_MCUXTDisplayUpper • FB_MCUXTDisplayLower • FB_MCUC4DisplayUpper • FB_MCUC4DisplayLower • FB_FP8Display • FB_FP16Display • FB_FP8DisplayUpper • FB_FP16DisplayUpper • FB_FP8DisplayUpperMiddle • FB_FP16DisplayUpperMiddle • FB_FP8DisplayLowerMiddle • FB_FP16DisplayLowerMiddle • FB_FP8DisplayLower • FB_FP16DisplayLower • FB_QConLiteDisplayUpper • FB_QConLiteDisplayUpperMid • FB_QConLiteDisplayLowerMid • FB_QConLiteDisplayLower • FB_MFT_RGB • FB_NovationLaunchpadMiniRGB7Bit • FB_FaderportRGB7Bit Virtual Widgets GeoffAWaddington edited this page on Dec 8, 2020 · 6 revisions If you read the Defining Control Surface Capabilities page, you'd know that we define Widgets in our .mst/.ost files to represent the capabilities of our surfaces. I sometimes think of these Widgets (or at least the Message Generator part) as triggers I can use to cause certain actions or behaviours to occur. If we run with that analogy, then the Widgets on our surfaces are not the only things we may want to use to trigger behaviours. Sometimes we may want to trigger them when certain things occur in Reaper itself, eg when the selected track changes. These are called Virtual Widgets. We don't have to define them in our MST files, as they are not coming from a control surface. We just need to use them in our zone files like any other Widget. The Virtual Widgets currently defined are: • OnTrackSelection - fires when a track is selected in Reaper. • OnFXFocus - fires when a VST plugin window receives focus in Reaper. • OnPageEnter - fires after a new Page has been entered. • OnPageLeave - fires before the the old Page has been exited. • OnInitialization -- fires when CSI initializes -- not valid for EuCon -- if needed for EuCon, will add later • OnEuConFXAreaGainedFocus -- fires when the INSERTS is selected. • OnEuConFXAreaLostFocus -- fires when the INSERTS is deselected. Defining Control Surface Behaviour GeoffAWaddington edited this page on Nov 19, 2020 · 7 revisions We define what behaviour should occur when particular widgets are pressed/turned/moved/etc in .zon files. If you remember in our CSI.INI file, for each surface we listed a number of things: MidiSurface AlphaTrack 8 8 AlphaTrack.mst AlphaTrack 1 0 0 0 In this example, the AlphaTrack.mst was where we defined what widgets were on the surface. The next item to the right, in this case 'AlphaTrack' is the name of a Zones folder. Inside this folder, we should create whatever .zon files we want that relate to the widgets on this surface. We can also use subfolders, and subfolders of subfolders and so on, in order to organize our .zon files. Note: You can put them all in one file, you can break them out in dozens of files, totally up to you. CSI will read in all the .zon files it finds in this folder, including all subfolders, so do whatever you find easier to manage. Inside these .zon files, we can create as many Zones as we like, to map the widgets on this surface to the actions we want to trigger. As you'll see on that page, we can also switch between currently active zones, compose zones out of other zones, etc. Types of Zones At this stage there are primarily two types of Zones that we can define: • Zones that control general Reaper functionality. eg. the Tracks in our project, the Transport controls, our Track Sends, etc • Zones that control VST instruments/FX inside Reaper. eg. How to map the parameters of your EQ, Reverb, etc on the selected track across your surfaces. They are both defined as Zones in .zon files, but there are some additional details for FX Zones that are worth discussing.Zones GeoffAWaddington edited this page on Nov 19, 2020 · 24 revisions 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. Naming Zones If your Zone name has a space in it, you'll need to wrap all references to it in quotes. Probably a good idea to wrap them all in quotes, spaces or not, just so you don't have to think about it. 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. I might group a bunch of widgets together into a zone called MasterButtons, because the actions I am assigning to them are conceptually related: Zone "MasterButtons" Track ToggleMapSelectedTrackFXMenu Send ToggleMapSelectedTrackSends Pan ToggleMapSelectedTrackFX Shift+Pan GoZone Home Plugin ToggleScrollLink ChannelLeft TrackBank "-1" ChannelRight TrackBank "1" BankLeft TrackBank "-20" BankRight TrackBank "20" Rewind Rewind FastForward FastForward Stop Stop Play Play Record Record F1 NextPage ZoneEnd As another example, I might define a zone called Channels 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 "Channel" TrackNavigator DisplayUpper| TrackNameDisplay TrackTouch+DisplayUpper| TrackVolumeDisplay Rotary| MCUTrackPan RecordArm| TrackRecordArm Solo| TrackSolo Mute| TrackMute Select| TrackUniqueSelect Shift+Select| TrackRangeSelect Control+Select| TrackSelect Shift+Control+Select| TogglePin Fader| TrackVolume FaderTouch| TrackTouch 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 Changing Zones We can also change which zones are active at the moment using an Action called GoZone: someButton GoZone anotherZone That is telling CSI to "overlay" that zone over the currently active zones. Any widgets used in anotherZone that were previously mapped in the currently active zones will now trigger the actions defined in the anotherZone. Any that aren't used in anotherZonewill keep performing the actions they were before we triggered GoZone. This results in a very flexible system where can temporarily change certain control's behaviour in response to whatever widgets and/or Virtual Widgets we like. 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. First, the entire section is preceded by a comment using a single forward slash. Then, each of the automation modes is followed by a trailing comment identifying which mode is which. /To make MCU Std mode work like MCU Cubase mode, I'm using F1-F5 on the X-Touch One for the automation modes. Zone "SelChannelButtons|" SelectedTrackNavigator F1 TrackAutoMode 1 //Read F2 TrackAutoMode 3 //Write F3 TrackAutoMode 0 //Trim F4 TrackAutoMode 2 //Touch F5 TrackAutoMode 4 //Latch ZoneEnd Send Zones FunkybotsEvilTwin edited this page 23 days ago · 6 revisions You can use CSI to create zones for any Sends on the selected track in Reaper. The CSI action MapSelectedTrackSendsToWidgets needs to be assigned to a widget (e.g. a button on your surface) or virtual widget (e.g. OnTrackSelection) to engage the sends. Then you'll also need a GoZone "Home" somewhere in your surface zone file to un-map sends and get back Home. Note: Sends are a special type of zone so your send zone must be named "Send" and must use the SendNavigator as shown below. Sends will then engage for the selected track in Reaper. Here's an example of a zone file that uses buttons to engage the send zone. Zone Home IncludedZones "Buttons" IncludedZonesEnd ZoneEnd Zone "Buttons" Send MapSelectedTrackSendsToWidgets Cancel GoZone "Home" ZoneEnd Zone "Send" SendNavigator DisplayUpper| TrackSendNameDisplay DisplayLower| TrackSendVolumeDisplay Mute| TrackSendMute Fader| TrackSendVolume Rotary| TrackSendPan RotaryPush| NoAction ZoneEnd You'll have to setup the number of Sends (example: I have 8 faders I want to map up to 8 sends to) in your CSI Device Preferences. FX Zones FunkybotsEvilTwin edited this page on Nov 25, 2020 · 15 revisions FX Zones are similar to normal Zones in that we are mapping Widgets defined in our mst files to behaviour we want to occur. The major difference is about what that behaviour is. In a normal Zone we're binding the widgets to some sort of action in Reaper, whereas for FX Zones, we're binding them to a parameter value in an FX plugin (eg. a VST, etc) A simple ReaEQ example As an example, I have one of my BCF2000's mapped to control ReaEQ. For each band I add, it maps an Encoder to control the Frequency, a Fader to control the Gain, and Shift plus the Encoder to control the Bandwidth/Q. The .zon file You'll need to create an "[plugin name].zon" file for each plugin you map. These are just .txt files with the extension changed to .zon and can be edited and created in any text editor. Do not put spaces or special characters in the .zon filenames. Using the example below, our file name would ultimately be: VST__ReaEQ__Cockos_.zon And here's an example of the contents of the following zon file: Zone "VST: ReaEQ (Cockos)" ReaEQ FocusedFXNavigator RotaryG11 FXParam 0 "Freq-Band 1" Fader1 FXParam 1 "Gain-Band 1" Shift+RotaryG11 FXParam 2 "Q-Band 1" RotaryG12 FXParam 3 "Freq-Band 2" Fader2 FXParam 4 "Gain-Band 2" Shift+RotaryG12 FXParam 5 "Q-Band 2" RotaryG13 FXParam 6 "Freq-Band 3" Fader3 FXParam 7 "Gain-Band 3" Shift+RotaryG13 FXParam 8 "Q-Band 3" RotaryG14 FXParam 9 "Freq-Band 4" Fader4 FXParam 10 "Gain-Band 4" Shift+RotaryG14 FXParam 11 "Q-Band 4" RotaryG15 FXParam 12 "Freq-Band 5" Fader5 FXParam 13 "Gain-Band 5" Shift+RotaryG15 FXParam 14 "Q-Band 5" RotaryG16 FXParam 15 "Freq-Band 6" Fader6 FXParam 16 "Gain-Band 6" Shift+RotaryG16 FXParam 17 "Q-Band 6" RotaryG17 FXParam 18 "Freq-Band 7" Fader7 FXParam 19 "Gain-Band 7" Shift+RotaryG17 FXParam 20 "Q-Band 7" RotaryG18 FXParam 21 "Freq-Band 8" Fader8 FXParam 22 "Gain-Band 8" Shift+RotaryG18 FXParam 23 "Q-Band 8" ZoneEnd Let's walk through the key pieces: • The first line Zone "VST: ReaEQ (Cockos)" ReaEQ defines the plugin that this zone is for, and needs to exactly match the name of the plugin as it appears in caption of the plugin window (see the first screenshot above, before the hyphen). • Note: If you rename a plugin in Reaper, your FX zone will need to be updated to match exactly. Anyone you share the FX .zon file with would either also have to rename their plugin in Reaper to match, or edit the .zon file to go back to the original name. • Don't worry about the second line above ("FocusedFXNavigator"), we'll deal with that below in the How to activate an FX Zone section. • We then have one line for each widget/plugin parameter mapping we want to create. As an example, the first one looks like this RotaryG11 FXParam 0 "Freq-Band 1" and breaks down as: ◦ RotaryG11 - the name of the widget ◦ FX Param 0 - the index of the plugin's parameter (I'll show you how to find that in a second) ◦ "Freq-Band 1" - this can be whatever name you want to give the parameter. Use this for your own reference in the .zon file. If you have a surface with displays and would like to learn how to see the FX Parameter Name and Parameter Values on the surface itself, see FX-Parameter-Mapping-Actions. Once you've created your .zon file, put it in the Zone directory for whatever Surface it refers to (the same folder you have your other Zone definitions for that surface. In theory you could even put it in the same file as the other zones for that surface, but this is not recommended. It's much easier, clearer and more reusable to go with one file per plugin. You may even create a dedicated "FXZones" subfolder within your surface zone just to separate FX .zon files from the surface .zon file. Finding Parameter Indexes Hopefully that's pretty easy, except for that Param Index issue. Where do we find them? One easy way I've found is to bring up the FX window in Reaper, and then click the UI button. As you can see, Reaper will display a list of all the params in can find for the plugin as it is currently setup. The first one is Index 0, the second one is index 1, etc. Note I said "as it is currently setup" just then. If you add another band to ReaEQ, you'll see you get more params added, so you might need to explore a little until you find all the params you need. Generating a Raw FX zon file • Run the Reaper action "CSI Toggle Write Params to /CSI/Zones/ZoneRawFXFiles when FX inserted" • Insert the FX of interest Result: if you navigate to your CSI\Zones\ZoneRawFXFiles folder, you should now see a "[plugin_name].txt" file. Open that file up, and you will see a list of all the FX Param numbers for every parameter in that plugin, along with the parameter name for easy reference. Here's an abbreviated example of what ReaEQ looks like... Zone "VST: ReaEQ (Cockos)" SelectedTrackNavigator FXParam 0 "Freq-Low Shelf" FXParam 1 "Gain-Low Shelf" FXParam 2 "Q-Low Shelf" ZoneEnd How to activate an FX Zone So, now we have our zone, we need a way to activate it. With normal zones, we could just GoZone to it using a widget, but with FX Zones it is slightly different. We have a couple of options: • Activate all the FX Zones for the currently selected track • Activate the FX Zone for the currently selected/focused FX window You can of course mix and match these, activating some FX Zones when the track is selected, and others only when the FX Window is focused, but any one FX Zone can only be activated by one or the other, not both. Action Reference GeoffAWaddington edited this page 21 days ago · 60 revisions CSI Actions Transport and Timeline • Rewind Transport Actions GeoffAWaddington edited this page on Nov 19, 2020 · 6 revisions The Transport Actions are fairly simple, and as a result, I often use them as "proof of life" actions when I'm first setting up a new surface mapping. If I can get a button on a surface mapped to the Play action, then I know I've got most of the basic setup for the surface working properly and I can move on to doing more advanced things. The Transport Actions are: • Rewind • FastForward • Play • Stop • Record • Loop • Return to the beginning on the timeline Little explanation needed for those, they map very directly to the buttons on Reaper's transport controls. They take no parameters, so if you want to map a Press widget to Play, you would put the following in your zone definition: PlayButton Play where PlayButton is the name of your widget. Tracks • TrackVolume • SoftTakeover7BitTrackVolume • SoftTakeover14BitTrackVolume • MCUTrackPan • TrackPan • TrackPanWidth • TrackPanL • TrackPanR • TrackSelect • TrackUniqueSelect • TrackRangeSelect • TrackSolo • TrackMute • TrackRecordArm • TrackNameDisplay • TrackVolumeDisplay • MCUTrackPanDisplay • TrackPanDisplay • TrackPanWidthDisplay • TrackPanLeftDisplay • TrackPanRightDisplay • TrackOutputMeter • TrackOutputMeterAverageLR • TrackOutputMeterMaxPeakLR Track Sends • TrackSendVolume • TrackSendPan • TrackSendMute • TrackSendPrePost • TrackSendInvertPolarity • TrackSendNameDisplay • TrackSendVolumeDisplay • TrackSendPanDisplay • TrackSendPrePostDisplay • MapSelectedTrackSendsToWidgets FX • FXParam • FXParamRelative • FXNameDisplay • FXParamNameDisplay • FXParamValueDisplay • FXMenuNameDisplay • FocusedFXParam • FocusedFXParamNameDisplay • FocusedFXParamValueDisplay • MapFocusedFXToWidgets • MapSelectedTrackFXToWidgets • MapSelectedTrackFXToMenu • GoFXSlot • FXGainReductionMeter Navigation • TrackBank • TogglePin • ToggleScrollLink • ForceScrollLink • NextPage • GoPage • GoZone • PageNameDisplay VCA • TrackToggleVCASpill • ToggleVCAMode Automation • TrackAutoMode • GlobalAutoMode • CycleTrackAutoMode • TrackAutoModeDisplay EuCon Specific • TrackVolumeDB • TrackPanPercent • TrackPanWidthPercent • TrackPanLPercent • TrackPanRPercent • TrackSendVolumeDB • TrackSendPanPercent • EuConTrackSendMute • EuConTrackSendInvertPolarity • EuConTrackSendPrePost • EuConTrackSendNameDisplay • EuConTrackSendVolumeDisplay • EuConTrackSendPanDisplay • EuConTrackSendPrePostDisplay • EuConTimeDisplay Other • NoAction • FixedTextDisplay • FixedRGBColourDisplay • ClearAllSolo Modifiers • Shift • Option • Control • Alt • InvertFB • Hold Reaper Actions Button1 Reaper "40454" Button2 Reaper "_0e5b196e7f67994bab6de09c49f05926" Button3 Reaper "_SWSTL_SHOWALL" Invokes the Reaper Action (custom o Modifiers GeoffAWaddington edited this page on Nov 19, 2020 · 32 revisions Modifiers are a way to indicate that you want one control to perform different actions under different circumstances. For example, this could be when another button is pressed in combination with the control (like your keyboard behaving differently when you hold the Shift key down), or it could be when a button is held down for a longer period of time. Global Modifiers To avoid creating dependencies between zone files (where a control specified in one is referenced in another), there are a set of global modifiers available: • Shift • Option • Control • Alt In your .mst file you can name one or more controls on your surface with whichever of these you wish to use: Widget Shift Press 90 46 7f 90 46 00 WidgetEnd Widget Option Press 90 47 7f 90 47 00 WidgetEnd Widget Control Press 90 48 7f 90 48 00 WidgetEnd Widget Alt Press 90 49 7f 90 49 00 WidgetEnd Now you can use them like this in any of your zone files, but for consistency, we should all put our modifiers in the "Buttons|" Zone, which is typically included in the "Home" Zone: Zone "Buttons|" Shift Shift Option Option Control Control Alt Alt Save Reaper 40026 Shift+Save Reaper 40022 Undo Reaper 40029 Shift+Undo Reaper 40030 ZoneEnd Additionally, any widget can be defined to act as a modifier... Zone "Buttons|" Zoom Shift Rewind Rewind Shift+Rewind Reaper 40042 //go to start of project ZoneEnd ...In the above example, the Zoom widget was defined within the zone to act as the Shift modifier. That Shift modifier can then be combined with other widgets like the Rewind button to trigger additional actions. In this case, pressing Zoom+Rewind will return to the start of the project. Modifiers are global to a page, and as long as they are defined in a zone somewhere in that page, they can be used anywhere. You can also combine them together, such as: Shift+Control+Option+Alt+SomeButton SomeAction etc., but note that Shift+Control is the same as Control+Shift Tip: If you've defined a Shift modifier, a quick press of that button will enter a latching mode where the Shift modifier will remain active until pressed again. Built-in Modifiers InvertFB Up is down, down is up, on is off, and off is on. Example: Reaper EQ FX bypass On means control surface EQ Active light should be Off. InvertFB+SomeButton FXParam 16 "Bypass" Hold A one-second hold of a button will result in a different action. For instance, pressing the "Click" button toggles the metronome, but holding the Click button opens the metronome settings. Important: for the Hold modifier to work, your button/widget must transmit release messages (otherwise, CSI will not be able to decipher between a hold and a button press). Click Reaper 40364 //Toggle metronome Hold+Click Reaper 40363 //Show metronome settingsr built in) specified by the ID in the argument Navigators GeoffAWaddington edited this page on Nov 19, 2020 · 16 revisions Navigators provide the context for the Actions triggered within our Zone. For example, if we’ve got a Fader widget bound to the TrackVolume action, which track will it change the Volume on? The selected track? The Master Track? Zone “MyWidgets” Fader TrackVolume EndZone Well, the answer depends on which Navigator we associate with the Zone: Available Navigators • SelectedTrackNavigator • TrackNavigator • MasterTrackNavigator • FocusedFxNavigator - See MapFocusedFXToWidgets for details • SendNavigator • FXMenuNavigator SelectedTrackNavigator Zone “MyWidgets” SelectedTrackNavigator Fader TrackVolume EndZone Using the SelectedTrackNavigator will mean that the actions in that Zone act in the context of the currently selected track. The Fader will change the selected track’s volume, TrackPan alters Pan settings, etc. SelectedTrackNavigator is especially useful for tasks like setting the automation mode, record arming, or toggling input monitoring states for the selected track if, for instance, your surface doesn't have multiple sets of buttons for these actions for each channel. SelectedTrackNavigator is how that one Read or Write knob can be setup to work on an 8-fader surface -- the single button sets the automation mode for the selected track only. Track Navigator Zone "Channel|" TrackNavigator Fader| TrackVolume ZoneEnd The TrackNavigator is what CSI uses to manage navigation and control of widgets that may impact multiple tracks. Example: you have an 8-fader surface with 8 rotaries, 8 solo, and 8 mute buttons that you'll want assigned to different tracks. This is where TrackNavigator differs from SelectedTrackNavigator - since we have more than one fader, and we will want to assign them to more than the selected track. In the above example, the faders are controlling TrackVolume across multiple tracks. You'll notice the use of the pipe character (located by pressing shift+backslash on your keyboard): see the section on setting up Zones for more details on why. MasterTrackNavigator Zone “MyWidgets” MasterTrackNavigator Fader TrackVolume EndZone Alternatively, using a MasterTrackNavigator means all those same actions act in the context of the Master Track. TrackVolume, TrackPan, etc will all affect the Master Track, regardless of which tracks are selected. SendNavigator Zone "Send" SendNavigator DisplayUpper| TrackSendNameDisplay DisplayLower| TrackSendVolumeDisplay Mute| TrackSendMute Fader| TrackSendVolume ZoneEnd FXMenuNavigator Zone "FXMenu" FXMenuNavigator DisplayUpper| FXMenuNameDisplay DisplayLower| NoAction Rotary| NoAction RotaryPush| GoFXSlot ZoneEnd Invoking Multiple Actions GeoffAWaddington edited this page on Nov 19, 2020 · 10 revisions Invoking multiple Actions from a single Control is as simple as defining more than one in your zone file, eg: Button1 TrackMute Button1 Reaper "40455" Ref: Example from Geoff The actions will be executed in the order they appear in the zone definition. Tips and Tricks FunkybotsEvilTwin edited this page 5 days ago · 7 revisions Latching Modifiers If your surface sends release messages on button press, then you can do a quick press and release to "latch" a modifier. Example: let's say you want to use a few actions that require a Shift modifier. Quickly pressing and releasing the Shift button will engage the latch mode, which is the same as continuing to hold down the Shift button. A quick press and release turns the latching off. Chaining Multiple Modifiers You're not limited to one modifier like Shift or Control or Alt. You can combine them to add additional capabilities to your surface. Here are some examples of what that might look like... Shift+Control+Button Control+Alt+Button Shift+Control+Alt+Button Shift+Control+Alt+Option+Button Modifiers Work on Displays Too! Did you know that you can use modifiers on your displays? Here is an example where the lower displays show the track volume, until you hold down Shift, when the TrackPans are displayed. DisplayLower| TrackVolumeDisplay Shift+DisplayLower| MCUTrackPanDisplay You Can Chain Actions For CSI "Macros" Want to run a few actions in a set sequence? Just create multiple lines in your .zon files with the actions in the order you want. CSI will trigger each action in the order from the .zon file similar to running a custom action (or macro). In this example, holding select will 1) select the track, 2) toggle the mixer setting to show/hide children in folders (which would only apply if a parent folder track), and 3) toggle VCA spill (which would only apply if a VCA master track). Hold+Select| TrackUniqueSelect Hold+Select| Reaper 41665 //Mixer: Toggle show tracks in folders in mixer Hold+Select| TrackToggleVCASpill "Refresh All Surfaces" Reaper Action to Test Changes to Your .zon Files If you're creating or modifying .zon files with Reaper open, and want to check out the changes, CSI will need to rescan the files. The most efficient way to do this (i.e. without needing to close and restart Reaper) is to run the Reaper action: Control surface: Refresh all surfaces ...this will allow CSI's parser to rescan your .zon files. Just remember to actually save the changes to your .zon files before you run it (speaking from experience)! Setting Up Your Phone or Tablet as an OSC Device in CSI FunkybotsEvilTwin edited this page on Nov 22, 2020 · 8 revisions Setting Up Your Phone or Tablet as an OSC Device in CSI CSI is compatible with MIDI, EuCon, and Open Sound Control (OSC) devices. OSC allows you to use a phone or tablet to interact with your CSI setup; essentially acting like another control surface. There are OSC compatible applications that you can download on your phone or tablet, and you can create OSC templates that can be programed to interact with CSI like any other program. This guide will focus on setting up the included Mackie C4 emulator OSC template using TouchOSC on an iPad. The exact instructions may vary from device to device, or depending on the OSC application you're using, but the high-level concepts should be similar regardless of device or application. Pre-Condition: 1. You’ve already setup CSI according to the Installation Instructions (including the OSC related folders and files) 2. Your phone or tablet must be on the same network as your PC or Mac Step 1: Download TouchOSC On Your Phone or Tablet First things first, go to the Android or iOS app store and download TouchOSC to the device you’d like to use. Step 2: Download and Install the TouchOSC Editor To Your PC or Mac The TouchOSC Editor can be found here: https://hexler.net/products/touchosc#downloads Step 3: Transfer the C4Emu TouchOSC Template to Your Phone or Tablet CSI comes with some TouchOSC templates, so we’re going to open the C4Emu template in TouchOSC editor, then add it to TouchOSC on our phone or tablet. 1. Open TouchOSC Editor 2. Click File -> Open 3. Navigate to the Reaper resource path folder where you installed CSI 4. Open the CSI\Touch OSC Layouts\ folder 5. Locate and open the C4Emu.touchosc file – the file will open 6. Click the “Sync” button in TouchOSC Editor 7. Open TouchOSC on your phone or tablet 8. Under where it says Layout click the current layout name. This will open the Layout selection screen. Note: If you’re already in a layout, click in the dot in the top-right-hand corner to go back. 9. In the Layout selection screen, the top row says “Add” click this 10. Under “Found Hosts” your PC name should appear – click the PC name You should now have successfully loaded the C4Emu.touchosc template to your device. Step 3 : Let’s Find Out Our Computer Host/Local IP Address The first thing we should do is find out what our Host Computer’s IP address (if you don’t already know). Lucky for us, Reaper can just tell us. So… 1. Open Reaper’s Preferences -> Control/OSC/WEB 2. Click Add 3. Select OSC (Open Sound Control) 4. In the Mode dropdown select “Configure device IP+local port) 5. See where it says “Local IP:” followed by a number? Example: 192.1.0.124 That’s your Local IP address. Make note of this. 6. Click CANCEL – we don’t actually want to create the OSC device in here, we just wanted to know what our IP address was. Step 4: Open the TouchOSC App on Your Phone or Tablet and Enter Your IP Address Here we are going to take the Local IP address from the prior screen, and enter it as the Host IP address in TouchOSC. We’re also going to make note of some device IP details for use later in Reaper/CSI. 1. Open TouchOSC 2. Where it says “Connections” select the first row “OSC” 3. Make sure OSC is enabled 4. Where it says “Host” enter your Local IP Address from the prior step 5. Now make note of your “Port Outgoing” (usually 8000) 6. Make note of your “Port Incoming” (usually 9000) 7. Make note of the “Local IP Address” (example: 192.1.0.193) – this is the IP address of your phone or tablet 8. We’ll need these to setup CSI Step 5: Create the OSC Device in CSI 1. Open Reaper’s Preferences -> Control/OSC/WEB 2. Click on Control Surface Integrator from the list (if it’s not already there, install CSI according to the Installation instructions). 3. Click Edit – the Control Surface Settings screen should open 4. On the Pages section on the left, click Home (or whatever page you want to add the OSC device on) 5. Click the “Add OSC” button 6. Name your device, example: iPad C4 7. Enter 8 channels, 8 sends, and 8 FX menus – this will give some flexibility later 8. Where it says “Remote device IP” this is the IP address of your Phone or Tablet from Step 4.7 above 9. "CSI Receives On Port" will be the Outgoing Port from Step 4.5 above (8000) 10. "CSI Sends on Port" will be the Incoming Port from Step 4.6 above (9000) 11. Where it says surface select MackieC4Emu.ost 12. Where it says zone select C4Emu 13. Hit ok to save and apply all changes 14. Close and restart Reaper. For whatever reason, at least here, OSC changes require a full restart of Reaper. If everything went according to plan, you’ve just mapped your phone or tablet to act as a control surface in Reaper+CSI. Ok, Now what? All we’ve done so far is connected your phone or tablet to Reaper+CSI. You still have to create .zon files for any FX or Reaper actions you’d like to control. See the rest of the Wiki for guidance on how to go about that. How To: Creating a Touch OSC Template, .ost File, and Zone for Use in CSI FunkybotsEvilTwin edited this page 14 days ago · 6 revisions Creating a Simple OSC Template and .OST Here, I’m going to show you how to create a simple single channel setup for a phone using TouchOSC Editor, that we’ll then create an .ost and .zon files for use in CSI. The goal of this guide is not to create the best TouchOSC layout ever, but rather, just expose you to the concepts so you can create your own TouchOSC devices in the future by expanding on what you learn here. Pre-Conditions: • You’ve got TouchOSC Editor installed on your computer • You’ve got TouchOSC installed on your phone or tablet • They’re all talking to each other and Reaper (see my other guide on setting up a similar configuration) Step 1: Create the Template in TouchOSC Editor Let’s create a very simple template in Touch OSC Editor. I want a remote control where I can record myself remotely, and use my phone for Play, Record, Stop, with Volume and Pan on the selected channel. I also want a display to show me the Selected Track Name. So 6 controls total. Sample CSI Phone Remote 1. Open TouchOSC Editor 2. Where it says Layout on the left, I’m going to keep the size at “iPhone/iPadTouch” with a vertical orientation (default settings) – You should pick the size and layout that best matches your device!!! 3. Below that where it says Page, then Name, pick a name for your page. It’s a best practice to name your pages. 4. If you want to make that name visible on the template, click on “Label” and you can enter the page name in the Text field, and pick a color. 5. Now, right click on the black background that represents the phone screen. This opens a dropdown menu of available controls/displays/etc. 6. Select “Push Button” 7. Drag that button towards the bottom right and resize it to your liking being careful not to make it so small the control will be difficult to operate. 8. With the button selected and highlighted, let’s change the color to Green. Check the box for Local Feedback Off. 9. Now, with the button still selected, enter the name “Play” at the top then go down to the OSC tab, uncheck the “Auto” button, and provide a name for this control of: /Play. Note: If you were going to use multiple pages on your TouchOSC template, you can include a page number or page name in the control name by using an extra set of slashes. Example: let's say you want to call it page 1, play widget. That would look like this /1/Play. Then on page 2 you wanted a rotary, that might look like /2/Rotary1. And so forth. But let's not do multiple pages and keep it simple with just /Play for now. CSI Phone Remote Play Button 10. Now right click a blank area and select “Label H.” 11. Drag this label over the middle of our button. 12. With the label selected, name this “PlayLabel” at the top-left hand side… 13. Change the color to Green 14. Resize it so it fills up most of the button 15. In the OSC tab uncheck auto 16. Label this control /PlayLabel 17. Uncheck the Background box 18. Where it says “Text” enter Play (this is what will appear in the label unless we tell CSI to show something else) 19. Change the size to something nice and big (say 20 or above) CSI Phone Remote Play Button Label 20. You’ve now created a button and a label 21. Let’s repeat these steps and create a Stop button (yellow) and a Record button (red) that we’ll put right above the Play button. We’re going to update all of our labels and locations to say Stop and Record respectively. You should end up with something like this. CSI Phone Remote Play, Stop and Record Buttons Now let’s add a Fader for volume, a Rotary for pan, and a Label for our Track Name! 22. Now Right-Click the black area again and select “Fader V” from the dropdown 23. Drag this to the left of our buttons and make the size something comfortable 24. Name this Fader1, maybe make it blue, with an OSC control name of /Fader1 – all other settings at default 25. If the thick part of the fader is at the top, then check the box to invert the faders. For some reason, inverted faders (drawbar style) appear to be the normal. CSI Phone Remote Fader Sample 26. Right click an empty space and select “Rotary V” 27. Move it above record and resize it 28. Let’s also make this blue, name it Rotary1, in the OSC tab give the control a name of /Rotary1 and leave all other settings at default CSI Phone Remote Rotary Sample One more control to go, let’s add a label. 29. Right-click an empty area and select “Label H” again 30. Let’s center this at the top 31. Resize it to make wider 32. Make the font size 18 or so 33. Label this “DisplayUpper1” with an OSC control name of /DisplayUpper1 and in the Text field lets add the text “Selected Track Name” [optional]. Completed Sample Do you have something that looks like this? 34. Now save your template! Step 2. Sync Your New Template to Your Phone or Tablet 1. In TouchOSC Editor click Sync 2. Open TouchOSC on your phone or Tablet 3. Find the layout selection and click the name of your currently selected layout 4. From the next window that appears, click Add 5. Wait until your PC appears under “Found Hosts” and click that PC name 6. This should automatically download your template to your phone or tablet 7. Go back to the Layout and select it 8. Click Done in the top right 9. You should now see your layout on your phone or tablet Step 3. Create a CSI .ost File for Your Template So now we need to define for CSI what controls exist in our template. So just as we need an .mst file for MIDI hardware, we need an .ost file for OSC templates. Being that we just created an OSC template from scratch, let’s create an .ost file from scratch too! • Open a text editor to begin creating your .ost file • Just like an .mst file, the first line is the word Widget followed by a description of that widget. • If it’s a control you’re going to go down a row and enter Control followed by the /[OSC_Control_Name] from our template. So our Play button would be /Play • If it’s a Feedback Processor (i.e. you need two-way communication) you need to define that. Controls usually have FB_Processors, but labels can be FB_Processors with no Control. You’re going to enter FB_Processor followed by the /[OSC_Control_Name] from our template. So our Play button would be /Play • The last row for each widget simply says WidgetEnd • Save your new .ost file in your CSI\Surfaces\OSC folder Here’s what I’ve setup. Notice that I didn’t create widgets for the labels for Play, Record, and Stop. That’s because I want that text to be fixed and static. Widget DisplayUpper1 FB_Processor /DisplayUpper1 WidgetEnd Widget Fader1 Control /Fader1 FB_Processor /Fader1 WidgetEnd Widget Rotary1 Control /Rotary1 FB_Processor /Rotary1 WidgetEnd Widget Play Control /Play FB_Processor /Play WidgetEnd Widget Stop Control /Stop FB_Processor /Stop WidgetEnd Widget Record Control /Record FB_Processor /Record WidgetEnd Step 4. Create a Zone Folder and .Zon File Now we need to tell CSI what to do with this new device by creating a zone folder and .zon file. • Create a new sub-folder under CSI\Zones for your device (Example: CSI\Zones\TouchOSC Remote) • Open up a Text Editor • Use standard CSI syntax for creating a zone file with 3 buttons, and a SelectedTrackNavigator zone with a Fader, Rotary, and Display. • Save this as a .zon folder in your new folder Your .zon file should look like this… Zone Home IncludedZones "Buttons" "SelectedChannel" IncludedZonesEnd ZoneEnd Zone "Buttons" Play Play Record Record Stop Stop ZoneEnd Zone "SelectedChannel" SelectedTrackNavigator Fader1 TrackVolume Rotary1 TrackPan DisplayUpper1 TrackNameDisplay ZoneEnd Step 5: Add Your Device to Your CSI Config and Restart Reaper 1. Open up Reaper’s Preferences 2. Go to Control/OSC/Web 3. Click on “Control Surface Integrator” (if not already there follow the installation instructions elsewhere in this wiki) 4. Click Edit to open the CSI preferences 5. Click the Page you’d like to add this surface to 6. Click Add OSC 7. Follow the instructions for adding an OSC device located elsewhere in this wiki 8. Click ok to save and apply your changes 9. Restart Reaper (OSC additions require a full restart)