Ableton Live Set Export

Ableton Live Set Export is a library that allows an application to write Ableton Live project files. The library handles generation of the ALS document, but also creates the project folder structure and copies any associated audio resources to the project. The library provides an Objective-C wrapper for iOS development.

The library only contains functionality for generating Ableton Live projects. It does not support reading or parsing Live Sets or other Ableton-generated files. This library also does not handle transmitting the project data from an iOS device to Live, or any other network operations. Ableton will provide separate UX guidelines to advise on how the library can best be integrated in your app.

Request Ableton Live Set Export

Concepts and Terminology

Live’s Session View: Live's Session View

Live’s Arrangement View: Live's Arrangement View

Creating a Live Set

The top-level class for creating Live Sets is the Project. A Project requires a creator name, which should be the name of the application that writes the Live Set. This string is also written to the song document itself.

The output of this library is a directory of files containing the Live Set and its associated audio resources. For iOS, Ableton recommends zipping the file using a framework such as ZipArchive, and then using the system-provided sharing dialog to export the Project.

Song properties

Aside from the creator name (which is required), songs have some properties which can be set:

Adding content to a song

Content may be added to either the session view or the arrangement view. The respective methods for adding clips to these views are clearly named, for example createSessionMIDIClip or createArrangementMIDIClipAt. When adding content to the session view, you can provide an optional scene index for the clip. If omitted, then ALSExportKit will insert the clip into the last scene, creating it if necessary. When adding content to the arrangement view, you must provide an offset and clip length in beat time.

After creating a project, either audio or MIDI tracks can be appended to it. A song must have at least one track, or else cannot be written to disk. Tracks cannot be reordered, they must be added to the song in the order which they should appear.

Once the song has some tracks, content may be added to them by adding clips. Unlike with tracks, clips may be added to arbitrary scene indexes within a track. When the song is written, any empty scene indexes will be populated with slots in all tracks. The scene indexes are only relevant for the session view.

For example, say that a song contains two tracks. A single clip is added to the first track. The first track now has one clip, which means that it also has one scene. The second track also has one scene with an empty slot, since all tracks must have the same number of scenes. Now another clip is added to the second track at index 3. Now both tracks have 4 scenes. The first track has a clip at index 0, and empty slots at indexes 1, 2, and 3, whereas the second track has empty slots at indexes 0, 1, and 2, and a clip at index 3.

Clip properties

After creating clips, their properties may be set to better suit the content which they contain. To create useful Live Sets, your application should set as many clip properties as it can, but any unset properties will use sane default values whenever possible.

Common clip properties

Audio and MIDI clips differ slightly in their supported properties, but they share a few common properties as well:

Audio clip properties

MIDI clips

MIDI clips don’t have any exclusive properties, but they can have any number of MIDI notes in a sequence. Live does not represent MIDI clips as actual MIDI files, and furthermore, this library does not expose all MIDI features which Live supports. Specifically, it only supports MIDI note on and note off messages (with velocity).

The API for adding notes to a MIDI clip relies on some basic knowledge of the MIDI protocol and how it represents note data. A good MIDI reference can be found here.

Use of labels

Live has several objects which can be labeled, including: clips, tracks, and scenes. Use of labels is a good way to organize Live Sets, and users will appreciate if content from the generating app has labels that they recognize. Specifically, if the app has text descriptions for content, then these strings should be set on the labels of the Live objects which they represent.

Each label may have an associated color as well. The label color feature should only be used if the generating app also makes use of colors to organize content. The label API has an enum with 10 common colors, and methods to find the nearest color given an RGB triplet. Label colors remain the same regardless of which skin has been selected by the user.

If your application does not use colors for organizational purposes, then it is best not to set a color on the associated Live content. In this case, a random color will be chosen for the object instead.

Live editions and restrictions

There are four editions of Ableton Live: Lite, Intro, Standard, and Suite. The commercially available edition features can be found here, and the Live Lite (OEM) features can be found here.

The differences between the various editions of Live are quite many, but in terms of this library, there are only a few key points to remember:

In the case of the scene/track count restrictions, attempting to load a document which has more content than the edition of Live permits will force Live into demo mode. In demo mode, saving or exporting content is not allowed, even if the user deletes some of the tracks or scenes to meet the restrictions. While this library does not impose a hard restriction on scene or track counts, it is important for app makers to understand these restrictions in case they want to warn Lite/Intro users about possibly incompatible Live Sets.

Live Lite compatibility

If your app is capable of generating more content than will fit in a Live Lite Set (8 tracks total, 8 scenes), then Ableton recommends creating two projects, one for each edition. Adding “Lite” or “Full” to the end of the Project name provides a good user experience, especially for Lite users.

Ableton suggests this practice so that Live Lite users do not try to open full sets with their edition, which may result in an error dialog and user frustration.

iOS integration

For iOS apps, simply add the libALSExportKit.a library from the lib subdirectory of the distribution zipfile to your project. You may also need to add the include subdirectory to your project’s list of header search paths in order to include the ALSExportKit.h header file.

ALSExportKit depends on the following frameworks, which will need to be added to your project settings:

Promoting Ableton Export Integration

After investing the time and effort to add Ableton Export to your app, you will probably want to tell the world about it. When you do so, please be sure to follow our Ableton Live Set Export promotion guidelines. This document contains both UI suggestions for integration and contains promotional guidelines and copy. Also available are the following promotional assets:

You can also find further press kits in our press area.