Max for Live provides two different ways to access the Live application
directly through the Live API:
Regardless of which method you decide to use, online documentation
for the
Live Object Model
describes the properties and functions of a Live session
that can be queried and set and observed.
You can get or set values, call functions, and observe the
status of properties using the Live API from any kind of
Max for Live device on any channel.
The Live API is described in
this overview .
The Live Object Model divides the Live application
into several basic functional units (properties) associated with
aspects of the Live application - the application itself, Songs,
Tracks, Clip slots, Clips, Devices, Device Parameters,
the Mixer Device, Scenes, Cue Points, And Control Surfaces.
The Live API provides ways to access some properties of the application to
control how the Live application displays them to you
(Application.View, Song.View, and Track.View).
Your use of the Live API involves one of four kinds of different operations:
-
You can query (get) the current state of a property
of your current Live session.
-
You can set the state of some properties of your
current Live session
-
Some properties can be controlled using functions
that perform various actions (e.g. firing a clip).
-
Some properties can be observed (i.e. their current state is
reported and updated automatically).
The
Live Object Model
provides a complete reference to which objects can be queried, set,
and observed, as well as a listing of the functions associated with them.
Max for Live includes a set of helpful
abstractions
that demonstrate how to interact with the Live API
in a Max for Live device.
The Live API abstractions
provide programming examples
and starting points for constructing your own patches that interact directly
with the Live application. They are grouped by the part of a Live Session
they can access and control.
You can use the Max for Live
live.path and
live.object
objects to find out the current state of any property defined in the
Live Object Model
reference.
The
live.path object
is used to navigate to the Live object properties you wish to query.
Each property of the Live object model in a session is
associated with an id specific to that particular Song,
Track, Clip, Clip Slot, Device, etc. Sending a message
to a
live.path object results in an object id
being sent out the left outout (where the id follows the
object) or middle outlet (where the id follows the path).
In turn, the
live.object object takes the id message from
the
live.path object and lets you use
get messages
to get information about the properties of the object.
The result of the query is sent out the outlet of the
live.object object, preceded by the name of the
query.
-
Using the Live Object Model, find the canonical path listing for the
property (in this case, the Track properties). This part of the
Live Object Model listing displays its
canonical path - the syntax for queries about the Track in a Live session.
-
Find the listing in the Live Object Model page for the
query you want to make (in this example, we want to to
see whether or not Track 3 is muted).
The listing from the
Live Object Model listing for the mute property of a Live Track
lists its Type as bool (boolean, 0 = off, 1 = on), and its
Access as get, set, observe, which means that this property can
be queried or set or observed (there's also an indication that
Live Master Tracks cannot be queried or set).
-
Use a
message box
to construct a message to be sent to the
live.path
object telling it the name of the property we want to query - Track 3
(by convention, track numbering in the Live API starts from 0).
In this case, the message is
path live_set tracks 3 .
The
live.path
object responds with the message
id N, where
N is the id number associated with Track 3.
-
use a Max
trigger
object to set up a sequence of operations. When the
trigger
object receives the list output, it sends the id message to the
live.object
object's right inlet, and then sends a bang message to the
message box
containing the symbol get, followed by the name of the property being queried.
In response, the
live.object
object sends the message mute 0
out the left outlet of the
live.object object
You can also use the Max for Live
live.path and
live.object
objects to set the current state of many properties defined in the
Live Object Model
reference.
The
live.path object
is used to navigate to the Live objects you wish to query.
Each property of the Live object model in a session is
associated with an id specific to that particular Song,
Track, Clip, Clip Slot, Device, etc. Sending a message
to a
live.path object results in an object id
being sent out the left outout (where the id follows the
object) or middle outlet (where the id follows the path).
In turn, the
live.object object takes the id message from
the
live.path object and lets you use
set messages,
followed by arguments that specify the new setting to set
the state of a property. In this example, we'll use a
set
message to mute Track 3 of a Live session.
-
Using the Live Object Model, find the canonical path listing for the
property (in this case, the Track properties). This part of the
Live Object Model listing displays its
canonical path - the syntax for queries about the Track in a Live session.
-
Find the listing in the Live Object Model page for the
query you want to make (in this example, we want to to
see whether or not Track 3 is muted).
The listing from the
Live Object Model listing for the mute property of a Live Track
lists its Type as bool (boolean, 0 = off, 1 = on), and its
Access as get, set, observe, which means that this property can
be set as well as queried and observed (there's also an indication that
Live Master Tracks cannot be queried or set).
-
Use a
message box
to construct a message to be sent to the
live.path
object telling it the name of the property we want to query - Track 3
(by convention, track numbering in the Live API starts from 0).
In this case, the message is
path live_set tracks 3 .
The
live.path
object responds with the message
id N, where
N is the id number associated with Track 3.
-
Use a Max
trigger
object to set up a sequence of operations. When the
trigger
object receives the list output, it sends the id message to the
live.object
object's right inlet, and then sends a bang message to the
message box
containing the message set, followed by the name of the
property we want to set and its new value - in this case, set mute 1 .
When you save and close the device and click on the upper message
box, Track 3 will be muted.
Some properties in the Live API can be
observed. The Live
API not only reports the current state of a property in response
to a query when it is observed, but also subsequently updates the
state of that property if it changes. Observing a property using
the Live API uses the
live.path object also used for getting
and setting properties, but also uses the
live.observer
objects to perform the task.
The
live.path object
is used to navigate to the Live objects whose functions
you want to call.
Each property of the Live object model in a session is
associated with an id specific to that particular Song,
Track, Clip, Clip Slot, Device, etc. Sending a message
to a
live.path object results in an object id
being sent out the left outout (where the id follows the
object) or middle outlet (where the id follows the path).
In turn, the
live.observer object takes the id message from
the
live.path object and lets you use
property messages
to define what property of the object you want to observe. In this
example, we'll observe whether or not Track 3 of our session is
muted or not.
-
Using the Live Object Model, find the canonical path listing for the
property (in this case, the Track properties). This part of the
Live Object Model listing displays its
canonical path - the syntax for queries about the Track in a Live session.
-
Find the listing in the Live Object Model page for the
property you wish to observe. Not all properties may be
observed via the Live API (in this example, we want to to
observe the behavior of muting on Track 3.
The listing from the
Live Object Model listing for the mute property of a Live Track
lists its Type as bool (boolean, 0 = off, 1 = on), and its
Access as get, set, observe, which means that this property can
be observed (there's also an indication that
Live Master Tracks cannot be observed).
-
Use a
message box
to construct a message to be sent to the
live.path
object telling it the name of the property we want to query - Track 3
(by convention, track numbering in the Live API starts from 0).
In this case, the message is
path live_set tracks 3 .
The
live.path
object responds with the message
id N, where
N is the id number associated with Track 3.
-
Use a Max
trigger
object to set up a sequence of operations. When the
trigger
object receives the list output, it sends the id message to the
live.observer
object's right inlet, and then sends a bang message to the
message box
containing the message property, followed by the name of the
property we want to observe - in this case, property mute .
When you save and close the device and click on the upper message
box while Track 3 is playing, you'll notice that the patch displays
a 0 (unmuted). If you mute the track by clicking on the Track Activator
button, you'll see the output of the
live.observer object
change to a 1 (muted). As you unmute and mute the track, the value
will change.
The Live API also includes various kinds of functions that
are used to perform activities such as changing various aspects
of the Live application's interface display (View) or controlling
the playing of clips or scenes.
You can also use the Max for Live
live.path and
live.object
objects to
call (perform) these functions.
The
live.path object
is used to navigate to the Live objects whose functions
you want to call.
Each property of the Live object model in a session is
associated with an id specific to that particular Song,
Track, Clip, Clip Slot, Device, etc. Sending a message
to a
live.path object results in an object id
being sent out the left outout (where the id follows the
object) or middle outlet (where the id follows the path).
In turn, the
live.object object takes the id message from
the
live.path object and lets you use
call messages,
followed by arguments that specify the name of the function
you're calling and any data for the function in the form of
arguments to execute the function. In this example, we'll use a
fire
function to play the clip in slot 2 or Track 2 of a Live session.
-
Using the Live Object Model, find the canonical path listing for the
property (in this case, the ClipSlot properties). This part of the
Live Object Model listing displays its
canonical path - the syntax for queries about the ClipSlot in a Live session.
-
Find the listing in the Live Object Model page for the
property's functions (in this example, we want to fire
(launch) the clip in clip slot 2 on Track 2.
The listing from the
Live Object Model listing for the fire function of the ClipSlot
property indicates that it needs no other data arguments.
-
Use a
message box
to construct a message to be sent to the
live.path
object telling it the name of the property we want to query - Clip
Slot 2 or Track 2
(by convention, all numbering in the Live API starts from 0).
In this case, the message is
path live_set tracks 1 clip_slots 1 .
The
live.path
object responds with the message
id N, where
N is the id number associated with Clip Slot 2 of Track 2.
-
Use a Max
trigger
object to set up a sequence of operations. When the
trigger
object receives the list output, it sends the id message to the
live.observer
object's right inlet, and then sends a bang message to the
message box
containing the message call, followed by the name of the
function - in this case, call fire .
When you save and close the device and click on the upper message
box while Track any other clip in any other clip slot in Track
2 is playing, you'll notice that the clip in Clip Slot 2 is launched.
The
live.object is designed to mimic user interactions with the
Live Session (and adds to undo history), so there are some situations that
involve rapid modulation of device parameters where the object may not
be appropriate. The
live.remote~ object allows you to directly
modulate the parameters of any "remotely mappable" control in Live at
signal rate.
As with setting values and calling functions, the
live.path object
is used to navigate to the Live objects whose functions
you want to control.
Each property of the Live object model in a session is
associated with an id specific to that particular Song,
Track, Clip, Clip Slot, Device, etc. Sending a message
to a
live.path object results in an object id
being sent out the left outout (where the id follows the
object) or middle outlet (where the id follows the path).
In turn, the
live.remote~ object takes the id message from
the
live.path object and accepts signal data in its left
inlet which is used to modulate or control the Live API property.
In the following example, we'll use the output of a
cycle~
object to control the sends on an audio track.
-
Using the Live Object Model, find the canonical path listing for the
property (in this case, the MixerDevice properties). This part of the
Live Object Model listing displays its
canonical path - the syntax for queries about the Track in a Live session.
-
Find the listing in the Live Object Model page for the
property you wish to control (in this example, we want to to
control the first send on Track 1. Remember that numbering
in the Live API starts from zero by convention.
-
Use a
message box
to construct a message to be sent to the
live.path
object telling it the name of the property we want to control.
In this case, the message is
path live_set tracks 0 mixer_device sends 0 .
The
live.path
object responds with the message
id N, where
N is the id number associated with the first send on
Track 1.
-
Add some logic to produce signal-rate data to control
the property. In this case, we're using a cycle~
device to use a sinusoidal waveform and then using the
abs~ (absolute value) object to keep the output
in the positive signal range.
When you save and close the device and click on the upper message
box while Track 1 is playing, you'll notice that the dial for
Send A on Track one moves at the rate you specify for the
cycle~ object.