discrete blogarithm

Writing Custom Control Surfaces for Ableton

Nov 7, 2019

Recently I’ve been really interested in what goes on in Ableton Live under the hood, since it’s a widely-used piece of proprietary software for making bangers. It turns out you can get pretty far knowing just a small amount of Python scripting!

For instance, I found that .als files (and .adv’s, and .adg’s, and probably more) are just gzipped XML and so therefore you can do some fun processing on them using any XML library, such as Python’s. So, remembering the week that it took me to convert all my Ableton DJ sets into Rekordbox, I wrote a script to automatically convert Ableton cues to Rekordbox and vice-versa. This could have definitely saved me about 10 hours of boring work time that could have been spent making bangers instead!

This week, I started looking into Ableton’s Python interface for control surfaces and you’ll never guess what happened next (a bunch of boring stuff).

What’s a control surface?

According to Ableton, “Control Surfaces are specially written scripts which allow controllers to interface with Live”.

Most people who use Ableton interact with it through a tactile controller, such as a MIDI keyboard or an Ableton Push or the APC40 controller. Control surfaces are scripts which act as a bridge between Ableton and the controller, telling Ableton what each button/knob/fader/etc. on the controller should do.

It turns out that these control surfaces are simply Python scripts.

Where does Ableton store its control surface scripts?

Ableton comes with a bunch of control surface scripts pre-installed for common controllers such as the Launchkey, Push, and APCs. For these controllers, you can just plug in the controller, open Ableton Preferences, and select the control surface for it via a drop-down list in the Link/MIDI tab.

These scripts are stored in /Applications/Ableton Live $VERSION.app/Contents/App Resources/MIDI Remote Scripts/ on Mac (where $VERSION is 10 Suite for instance if you have Live 10 Suite installed) and \ProgramData\Ableton\Live x.x\Resources\MIDI Remote Scripts\ on Windows.

For the rest of this post we will refer to this as the MIDI Remote Scripts directory.

Loading a custom control surface script

If you want to load your own custom control surface script for an existing MIDI controller, the steps are fairly straightforward:

  1. Find the existing control surface for the MIDI controller in the MIDI Remote Scripts directory. For instance, for the APC40, this would be in APC40/ as a bunch of .pyc files. You can either decompile the .pyc yourself or find the decompiled version in https://github.com/gluon/AbletonLive10.1_MIDIRemoteScripts.
  2. Copy these decompiled Python files to a new directory in the MIDI Remote Scripts directory.
  3. Customize them (more on this in the next section).
  4. Now open Ableton and go to the Link/MIDI tab of Preferences. Ableton should automatically compile the .py files to .pyc. If everything loaded without errors, you will see your new MIDI Remote Scripts directory show up as an option in the Control Surface dropdown.

Customizing control surfaces

In the MIDI Remote Scripts directory, there’s various directories that start with _. These are libraries which other control surfaces can make use of. One particularly useful one is _Framework, which includes definitions for useful classes like ButtonElement, which represents a button on the controller.

The best intro I’ve found to _Framework is this one by Hanz Petrov: https://livecontrol.q3f.org/ableton-liveapi/articles/introduction-to-the-framework-classes/.

Let’s say we want to take the Metronome button on an APC40MKII and instead map that to turn on looping for the currently active clip. Assume we’ve already created a ControlSurface subclass as a starting point.

  1. As a shortcut to calling ButtonElement directly, note that there is an _APC library already which provides a make_button utility method for APC controllers. Github link here.
  2. make_button takes an identifier as input. To figure out what we need to pass here for the metronome button, we can look at the APC control protocol documentation which conveniently lists identifiers for all the buttons on the APC40MKII. We see that 0x5a, or 90, is the identifier for the metronome button.
  3. Now we have to add a listener to the button using the add_value_listener method of ButtonElement that triggers when the button is pressed. Let’s call this handler start_loop.
  4. In start_loop, we can call the song() method of the ControlSurface superclass in order to get a reference to the Live.Song.Song object that we are currently controlling. For documentation on this and other Live objects that are available in Python, see here.
  5. song().view.highlighted_clip_slot.clip now gives us the active clip. This is a Live.Clip.Clip object according to the docs above. So we can simply set clip.looping to a truthy value like 1 to make the clip loop!

In reality, I’ve found the best way to figure these things out is to simply copy/paste code from other control surface scripts as needed. In particular, Will Marshall’s unsupported Ableton 8 control surface scripts are really helpful. Also the unofficial Live Python API documentation is crucial.

Debugging tips

  1. You can log to Ableton’s main log file using the ControlSurface log_message method defined here. On Mac, the log file is at /Users/[username]/Library/Preferences/Ableton/Live x.x.x/Log.txt and on Windows it’s \Users\[username]\AppData\Roaming\Ableton\Live x.x.x\Preferences\Log.txt. This file also contains errors emitted by Python.
  2. You can also reload the MIDI control surface without restarting Ableton: simply re-open the currently open session from File > Open Recent Set.
  3. If you find that Ableton doesn’t auto-compile Python, you can compile using python -m compileall .
  4. As mentioned previously, if a script throws an error immediately, it won’t show up in Ableton’s list of available control surfaces.

Example

As an example, see this Youtube video and Github repo for adding CDJ-style looping buttons to the APC40MK2. The work for this was done originally for Ableton 8 by Will Marshall and I only made some minor edits to make it more CDJ-like and loadable in Live 10.

Note that you can accomplish much of this already without control surface scripts simply by using Ableton’s MIDI mapping mode. One exception is the ability to halve and double loop lengths.

I hope this helps to show that control surface scripts are a quite powerful and flexible way to get your Ableton controller to behave exactly the way you want. Happy hacking!