How To: Creating a Touch OSC Template, surface.txt File, and Zones for Use in CSI - FunkybotsEvilTwin/CSIUserGuide GitHub Wiki

Creating a Simple OSC Template and surface.txt File

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 a surface.txt and set of .zon files for use in CSI. The goal of this guide is not to create the best TouchOSC layout ever, but rather, to 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)

Note: These instructions were created using a legacy version of TouchOSC but the same concepts apply to more up to date versions, or even other OSC applications.

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

  1. Now right click a blank area and select “Label H.”
  2. Drag this label over the middle of our button.
  3. With the label selected, name this “PlayLabel” at the top-left hand side…
  4. Change the color to Green
  5. Resize it so it fills up most of the button
  6. In the OSC tab uncheck auto
  7. Label this control /PlayLabel
  8. Uncheck the Background box
  9. Where it says “Text” enter Play (this is what will appear in the label unless we tell CSI to show something else)
  10. Change the size to something nice and big (say 20 or above)

CSI Phone Remote Play Button Label

  1. You’ve now created a button and a label
  2. 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!

  1. Now Right-Click the black area again and select “Fader V” from the dropdown
  2. Drag this to the left of our buttons and make the size something comfortable
  3. Name this Fader1, maybe make it blue, with an OSC control name of /Fader1 – all other settings at default
  4. 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

  1. Right click an empty space and select “Rotary V”
  2. Move it above record and resize it
  3. 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.

  1. Right-click an empty area and select “Label H” again
  2. Let’s center this at the top
  3. Resize it to make wider
  4. Make the font size 18 or so
  5. 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?

  1. 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 surface.txt 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 a surface.txt file for OSC templates. Being that we just created an OSC template from scratch, let’s create an surface.txt file from scratch too!

• Open a text editor to begin creating your surface.txt file

• For any control or display, 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 surface.txt file in your CSI\Surfaces[SurfaceName] 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 Files

Now we need to tell CSI what to do with this new device by creating a Zone folder and .zon files.

• Create a new surface folder structure (e.g. CSI\Surfaces\[SurfaceName]\Zones\HomeZones\ for your device

• Open up a Text Editor

• Use standard CSI syntax for creating zone files

Your .zon files should go in the [SurfaceName]\Zones\HomeZones\ folder

Home.zon

Zone Home
     IncludedZones
          SelectedTrack
     IncludedZonesEnd

     Play	Play
     Record	Record
     Stop	Stop
ZoneEnd

SelectedTrack.zon

Zone SelectedTrack
     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)