Basic information about the Live API and links to further readings.
This document refers to Ableton Live version 9 or newer.
Introduction
Besides building new instruments and effects to be used in Live, Max For Live also allows to access Live itself, its tracks, clips, devices and hardware control surfaces. This chapter defines some basic terms used throughout the whole Live API and introduces the Max objects representing the Live API.
Live Object Model
The accessible parts of Live are represented by a hierarchy of objects
called the
Live Object Model (LOM)
.
The model describes the hierarchy of objects inside Live, as seen from the
Max devices. There are various classes of objects in the model, like
or
. For certain objects only a single instance exists, for other multiple
instances are hold in lists. The
Live Object Model reference
shows how to navigate from a number of root objects down a path to the
particular object of interest, and what to do with it.
Object Path
Live objects are accessed using paths according to the Live Object Model.
For example, the first clip in the third track can be accessed by the path
As you can see, different paths can point to the same Live object. One of
these paths is the
canonical path
.
When communicating with the Live API, no quotes are used in paths. List
indexes start with 0.
When navigating through the object model, besides these
absolute
paths,
relative
paths can be used. These determine a subpath beginning at the current
position in the object hierarchy.
Root objects
(Absolute) paths to all objects start with one of
, , or . These are the root objects.Canonical Path
Different paths can lead to the same object.
Each object has a unique canonical path,
in this case. The canonical path is send out of
live.object
in reponse to
. In the Live Object Model, the canonical path is shown by bold connectors.
Canonical Parent
Additionally to what is described in the LOM, all objects have a
child which is used by Live to determine the canonical path of an object. The canonical parents are get-only and useful for patching, too. For example, is the perfect way to get the own track object.Object ids
An object id identifies a particular object instance in Live like a track
or a clip.
To get an id, a
live.path
object must be used to navigate to the Live object. When a
live.path
object sees this Live object the first time, an id is assigned to it.
The id is only valid inside the device with the
live.path
and remains unchanged as long the object exists. If the object is moved in
Live, its id usually remains unchanged. There may be exceptions if the
movement is implemented as a delete/create sequence, though. When an object
is deleted and a new object is created at its place, it will get a new id.
An id is never reused in the scope of a Max device. Ids are not stored.
Therefore, after loading a saved device, the
live.path
object must navigate to the object again.
An object id consists of the word
and a number, separated by a space, like
.
refers to
no object
. In Max terms it's a list of the symbol
and an integer.
Object Types
Each Live object is of a particular object type (or Class ). This object type determines what kind of object that is and what children, properties and functions it has. The object types are described in detail in the Live Object Model.
Children
Live objects have children identified by name. The names of the possible
children of some names point to single objects, others to a list of objects.
The child name also determines which object type you can expect to find
there.
List names are in plural, whereas single child names are in singular. Lists
may be empty. Sending
to
live.path
allows to find out how many children are in the list.
Single children names may point to no object, in which case you get
if you navigate there or send
to
live.object
.
Most children can be monitored using
live.observer
.
Properties
Live objects have properties which describe it's actual state. Properties
are accessed by sending
live.object
. Not all properties can be set, though.
Many properties can be monitored using
live.observer
.
Functions
Many Live objects have functions which can be called by the respective message to live.object . A function call may have parameters (a list of values) and a single return value, which is sent to the outlet of live.object .
Datatypes
Properties and function parameters or return values used in the Live Object
Model and by the Max objects to access the Live API have one of the
following data types:
Datatype | Description |
---|---|
bool | 0 for false and 1 for true |
symbol |
a string with unicode character set
use double quotes in message boxes to create symbols with spaces double quotes in symbols are to be prefixed by backslashes backslashes are included as double backslashes example: creates the symbol |
int | a 32 bit signed integer |
float | a 32 bit float value |
double | a 64 bit float value (maily used for timing values) |
beats | song beat time counted in quarter notes, represented as double |
time | song time in seconds, represented as double |
time = beats * 60 / tempo (in bpm) | |
sometimes the time is given in milliseconds (ms) | |
list | a space separated list of the types above |
Notifications
When Max devices need to know the state of the Live application and its
objects, they can actively poll the state by navigating through the object
hierarchy and getting object properties or calling functions.
But changes happen in Live while the Max device is passive. To allow the
Max device to react on these changes in Live, notifications are sent from
Live to the Max device. Notifications are spontaneous in the sense that
messages are sent to outlets spontaneously,
not
in response to a message received at an inlet.
The notifications include object ids sent when the Live object at a certain
path changes and values sent when a property changes.
Note: changes to a Live Set and its contents are not possible from a notification. The error message in the Max Console is 'Changes cannot be triggered by notifications'. In many cases putting a deferlow between the notification outlet and the actual change helps to resolve the issue.
Max Objects
Four Max objects interact in a certain way to allow Max devices to access
the Live objects.
Max object | Purpose |
---|---|
live.path | select objects in the Live object hierarchy |
live.object | get and set properties and children, call functions |
live.observer | monitor properties and children |
live.remote~ | control Live device parameters in real time |
The following patch shows the typical interconnections between the Live API objects. live.path is sending object ids out of its leftmost outlet connected to the rightmost inlet of live.object , live.observer and live.remote~ . This causes these objects to operate on the object selected by live.path .
live.path
live.path
objects are used to navigate to the Live objects on which
live.object
,
live.observer
and
live.remote~
are supposed to operate. For this purpose, navigation messages like
are sent to
live.path
, which replies by sending an object id to the left outlet.
live.path
can also observe the given path, and when the object at this path changes,
its id is sent to the middle outlet. This is particularly useful for paths
like
which point to the currently selected track.
live.object
live.object is used to operate on a particular Live object which id has been received from live.path . It allows to get or set properties of the Live object and to call its functions with parameters.
live.observer
live.observer monitors the state of a particular Live object which id has been received from live.path . After telling live.observer which property to observe it recognizes all changes of the property and sends the current values to its left outlet.
live.remote~
live.remote~
receives the id of a DeviceParameter object from
live.path
and then allows to feed this parameter with new values by sending them into
the left inlet, in realtime, without effects on the undo history or the
parameter automation, which is deactivated.
DeviceParameter objects are children of Live devices, including Max
devices, and also of tracks, like volume and pan.
LiveAPI
The LiveAPI Javascript object is available in code written for the js object. It provides a succinct means of communicating with the Live API functions from JavaScript, incorporating the functionality provided by the live.path , live.object and live.observer objects.
See Also
Name | Description |
---|---|
Max For Live | Max For Live |