Creating a Controller Template

A ‘Controller Template’ in Control Surface Studio is a virtual representation of a physical MIDI Controller i.e. an Akai APC40, Novation Launchpad, Ableton Push. 

The Controller Template contains all of the required MIDI Message data for the Midi Controller. 

It's important to note that Controller Templates don't actually contain any of your custom Ableton live functionality.

That all lives in a 'Script' (see Creating a Script)
A Controller Template is attached to a Script.

Then, within the script you can choose from all of the available inputs whichare available in the Template (knobs, sliders, buttons etc). 

Why are Controller Templates and Scripts separate?

The reason for this separation of 'Controller Templates' and 'Scripts' is to remove the need to re-enter MIDI data in each script.

Change a Controller Template's MIDI settings, then all scripts which use this template will automatically use the new settings when installed into Ableton. 

You can even change which Controller Template a script uses, making it quick and easy to port a script to multiple different Midi Controllers.

Once you have a Template for your Midi Controller, you can create endless Ableton scripts for it without needing to go through the hassle of adding MIDI message data each time.

The following diagram illustates how a single Midi Fighter Twister Controller template can then be re-used as the base for multiple Scripts.

Pre-built Controller Templates

If there is already a pre-built Controller Template for the MIDI Controller you want to use, then you can skip this step completely. Just make sure that the MIDI settings for the physical inputs on your Midi Controller, are set to the same as what is in the Controller Template.

You can check this by opening the settings form for each input in the Controller Template. This will usually be the Midi Controller's factory defaults, so if you have changed these on your unit, you will likely need to restore them back to the factory default.

You will can find Pre-built Controllers in the Controller Template's Import Section of Control Surface Studio or in the Forum.

Building a Controller Template from scratch

Open the Controller Template Manager

In the very left column menu (The Manager Selector), click the second Icon, this will display the Controller Template  Manager. 

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

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

Rename the 'Controller Name' field to the name of your MIDI Controller. Square Size, Grid Height & Grid Width are settings for the Visual MIDI Controller Area. This is the white section to the right which displays all of the inputs in the Controller Template. If the grid is not currently displayed, open the settings menu and check the ‘Show Grid’ box.

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.

Use the plus (+) and minus (-) buttons to add and remove rows. Colour Assignments set here will appear as LED Feedback options in the Script. Next you will see options for setting default LED On and LED Off settings for the Controller. For the majority of Controller, On is '127' and Off is '0' but please check this for your specific Controller.

Adding Controller Inputs

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

Select the ‘Button’ input type. 'Button 1’ is added below your Controller Template in the Controller Template Manager and it’s Settings Menu is displayed.

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

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

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). You can also click and drag your Button into position and the Left / Top settings will automatically update.

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’ ‘center’, 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.

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.

Turn on MIDI Monitoring

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

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.

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

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.

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.

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.

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 ).

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’.

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

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

Exporting and Sharing your Controller

Each Controller has an Export Button. Clicking this will display a standard 'Save As' dialog box. The file which is exported is a JSON file that contains all of the configuration information for your Controller.

This file can be imported into the App from the Import screen which is found at the top right of the Controller Template Manager Area.

Why not upload your creations to our Forum for other users to download and try it out or even try importing other people's creations into your own App.