Step by Step Tutorial

Creating a Controller

John Carney's picture by John Carney last updated Feb 23, 2019

A ‘Controller’ in Control Surface Studio, contains all of the MIDI Message data for a physical MIDI Controller. Controllers are virtual representations of physical Controllers and contain all of the required MIDI Data.
You then use Controllers in conjunction with custom 'Scripts' which provide the customisable functionality for Ableton Live.

The purpose of having separate Controllers and Scripts is so that you only need to create the Controller 1 time.
After that you can keep creating Scripts for your Controller without needing to go through this Step each time.

In this example for the MIDI Fighter Twister, we have created a single Controller in Control Surface Studio (CSS) . This Controller can then be re-used as the base for multiple Scripts.

Script and Controller Diagram

You can skip this step completely if there is already pre-built Controller for the MIDI Controller you want to use.
You will find Pre-built Controllers in the Import Section of Control Surface Studio or in the Forum.

Let's build a Controller.

Open the Controller Manager

In the very left column menu (Manager Selector), click the second Icon, this will display the Controller Manager in the black column to the right.

The manager column

Add a new Controller by clicking the plus (+) icon in the header of the Controller Manager. A new Controller named “New Controller” (how convenient) will appear below, and it’s settings menu will automatically appear to the right.

Add a Conroller

You can show and hide the Settings Menu by clicking the Cog Icon immediately to the right of its name.

settings menu icon

Rename the 'Controller Name' field to the name of your MIDI Controller.

Square Size, Grid Height & Grid Width are settings for the MIDI Controller Area.
The MIDI Controller Area is the white section to the right. If the grid is not currently displayed, open the settings menu and check the ‘Show Grid’ box.

The MIDI Controller Area

If you change Square Size to 10, you will see the squares on the grid shrink.
I usually keep them at the default setting of 15 but it’s up to you.

To display a Colour LED, MIDI Controllers use MIDI Velocity Values from 0 - 127 and each Controller has its own set of colour values. Your MIDI Controller's User Manual may contain this information in a ‘MIDI Implementation’ section.
If you know the Color Values for your Controller, enter them now.

Add the Colour name in the input box, then select the corresponding Velocity Value in the select list.

Colour Assignments

Use the plus (+) and minus (-) buttons to add and remove rows.

The LED Feedback functionality is actually set in the Script, but it’s helpful to add the details here for future reference.

Adding Controller Inputs

Click the (+) icon to the right of the Controller name, the 'Input Type Menu' will display.

the input type menu

Select the ‘Button’ input type.

'Button 1’ is added below your Controller in the Controller Manager and it’s Settings Menu is displayed.

Button 1

The Button’s visual representation is also displayed in the MIDI Controller Area.

Button 1 displayed visually

It’s visual size, shape and position are set using options in the button's Settings Form.

Button size and shape

Buttons can either be round or Square/Rectangular. We will leave ours as ‘round'.
Left & Top set the Button's position (measured in grid squares) from the left/top corner of the MIDI Controller Area.
We will leave ours in it’s default position (left 4, top 2).

button position

If the Button is set to 'Round', Radius sets the size of it.

Normally an Input’s Left & Top position will use the top left corner of the Input for setting it’s position.
If you set ‘Align to’ ‘centre’, then the centre of the Button is used to position it instead.
This is useful for ensuring that the centre of round buttons align correctly with other inputs on your Controller.

Align to Centre

If you know the MIDI Message information for your Input you can select it manually but in reality you’re probably not going to.
To work this out, we’re going to use MIDI Monitor to automatically set it for us.

In the header, click the ‘MIDI Monitor’ Icon to open it.

MIDI Monitor

Turn on MIDI Monitoring

turn midi monitor on

‘Connected MIDI Inputs’ will immediately update with a list of all MIDI Controllers connected to your computer.

Connected MIDI Inputs

Press the button on your MIDI Controller that you want to use.
Under ‘Latest MIDI Message received’ you will see data appear next to Channel, Type, Value & Velocity.
This is the MIDI Data for your Button.

Latest MIDI Message Received

You will see that this has been updated in the settings form also.

MIDI Settings

Under 'Control Type’, set the ‘On’ and ‘off’ values.
Use the 'Velocity' value in the MIDI Monitor. Add the Velocity value of when the Button is 'On' and the Velocity Value of when the Button is Off.

MIDI Velocity

And set the 'Switch Type’ to Momentary or Toggle depending on button’s switch type.
It’s important that this corresponds correctly with the correct type for the physical Button.

Switch Type

Note: You can override your button's control type in your Script to act differently. Switching a Momentary button to behave more like a Toggle for example, is possible.

Your changes are automatically saved. Let’s add a knob to your Controller next.

Add a knob

Click on the (+) icon to open the 'Input Type' Menu, and select ‘knob’.

We want to move the knob so it isn’t on top of our button,
In the Knob’s settings form, change the value of ‘Left’ to 11 and ‘Top’ to 2.

Knob Position in the MIDI Controller Area

Set the MIDI Type, Channel & Value as you did before using the MIDI Monitor.

Is your Knob ‘Absolute' or ‘Relative’?

Open the MIDI Monitor and slowly turn your Knob left then right.
If the Velocity Value in MIDI Monitor is outputting a stream of Values from 0 all the way to 127, set your Knob as 'Absolute' and for 'First' & 'Last' Input fields, use the velocity values at the left and right most points (Note that ‘First’ must always be the lower of the 2 values, you can use the Invert option to reverse the direction of you need to ).

Use MIDI Velocity to set first and last

If your knob only outputs 2 values (1 while turning to the left and another while turning to the right) then select Relative and input the left and right velocity values.

You can invert the direction of your knob by setting ‘Invert’ to ‘On’.
Leave Takeover mode set to ‘None’. For more details on this, see the takeover in the documentation.

Add a Container

The Container input type is purely for adding a visual box around your controls in the MIDI Controller area.
Open the Input Type Menu and select ‘Container’.

Container Input Type

In the settings menu, adjust the Width, Height, Left and Top settings so that the Container is wrapped around your controls.

Container dimensions and position adjusted

Click the Cog icon to close the Container’s settings menu.

Sharing your Controller

In Explorer (windows) or Finder (Mac), open your home folder and go to:
Control Surface Studio / Controller
Each file contained in here is a Controller in your Controller Manager.

File Browser displaying Controller json file

The order of the files in the Controller folder is usually the same as in Controller Manager.
To make sure you have the right Controller file, open it in a text editor and search for “name” to find the name of the Controller.

The Controller name inside the json file

Why not upload your creations to our Forum for other users to download and try it out.