LOM - The Live Object Model

What objects you find behind the Live API and what their structure, properties and functions are.

Introduction

The Live Object Model lists a number of Live object classes with their properties and functions as well as their parent-child relations through which a hierarchy is formed. Please refer to the Live API overview chapter for definitions of the basic Live API terms and a list of the Max objects used to access it.

This document refers to Ableton Live version 8.1b7.

Object Model Overview

Click on the classes to navigate to their description.

Application

This class represents the Live application. It is reachable by the root path live_app.

Canonical path

live_app

Children

Name Type Access Description
view Application.View get

Properties

None

Functions

Name Description
get_document Returns: the current live set.
get_major_version Returns: the 8 in Live 8.1.5.
get_minor_version Returns: the 1 in Live 8.1.5.
get_bugfix_version Returns: the 5 in Live 8.1.5.

Application.View

This class represents the aspects of the Live application related to viewing the application.

Canonical path

live_app view

Children

None

Properties

None

Functions

Name Description
available_main_views Returns: view names [list of symbols]. This is a constant list of view names to be used for the other functions: Browser Arranger Session Detail Detail/Clip Detail/DeviceChain.
focus_view Parameter: view_name
Shows named view and focuses on it
hide_view Parameter: view_name
is_view_visible Parameter: view_name
Returns: [bool]
scroll_view Parameters: direction view_name modifier_pressed
direction [int] is 0 for up, 1 for down, 2 for left, 3 for right
modifier_pressed [bool] has no effect at the moment
Not all views are scrollable, and not in all directions. Currently, only the Arranger, Detail/Clip, and Detail/DeviceChain views can be scrolled.
You can also pass an empty view_name "", which refers to the arranger or the session (whichever view is visible).
show_view Parameter: view_name
zoom_view Parameter: direction view_name modifier_pressed
direction [int] is 0 for up, 1 for down, 2 for left, 3 for right
modifier_pressed [bool] if 0 and view identifier results in arranger and direction is up or down, then only the hight of the highlighted track is changed, otherwise the height of all tracks is changed
Not all views can be zoomed, only arranger and detail clip.

Song

This class represents a Live set. The current live set is reachable by the root path live_set.

Canonical path

live_set

Children

Name Type Access Description
tracks list of Track get, observe
return_tracks list of Track get, observe
master_track Track get
visible_tracks list of Track get, observe A track is visible if its not a subtrack folded in. Hiding tracks be scrolling them out of view is something completely else.
scenes list of Scene get, observe
cue_points list of CuePoint get, observe Cue points are the markers in the arranger to which you can jump.
appointed_device Device get, observe The appointed device is the one used by control surfaces unless they control themselves which device to use. it is marked by a blue hand.
view Song.View get

Properties

Name Type Access Description
back_to_arranger bool get, set, observe Indicates the current state of the back to arrangement button located in the Live application's transport bar: 1=highlighted. This button is used to indicate that the current state of the playback differs from what is stored in the arrangement.
can_jump_to_next_cue bool get, observe The reason why it can't jump (0=cannot jump) is that there is no cue point to the right of the current, or none at all.
can_jump_to_prev_cue bool get, observe The reason why it can't jump (0=cannot jump) is that there is no cue point to the left of the current, or none at all.
can_redo bool get 1=there is something in the history to redo.
can_undo bool get 1=there is something in the history to undo.
clip_trigger_quantization int get, set, observe Reflects the quantization setting in the transport bar.
0: None
1: 8 Bars
2: 4 Bars
3: 2 Bars
4: 1 Bar
5: 1/2
6: 1/2T
7: 1/4
8: 1/4T
9: 1/8
10: 1/8T
11: 1/16
12: 1/16T
13: 1/32
current_song_time float get, set, observe Live set play position in beats.
exclusive_arm bool get Current status (1=set) of the exclusive arm option set in the record preferences.
exclusive_solo bool get Current status (1=set) of the exclusive solo option set in the record preferences.
groove_amount float get, set, observe The groove amount from the current set's groove pool (0. - 1.0).
is_playing bool get, set, observe 1=the Live transport is running. Can be used to stop or start the Live transport.
last_event_time float get The beat time of the last event (i.e. automation breakpoint, clip end, cue point, loop end) in the arranger.
loop bool get, set, observe 1=arranger loop is active.
loop_length float get, set, observe Arranger loop length in beats.
loop_start float get, set, observe Arranger loop start in beats.
metronome bool get, set, observe 1=the metronome switch in the transport bar is turned on.
midi_recording_quantization int get, set, observe Reflects the current selection of the Edit->Record Quantization menu.
0: None
1: 1/4
2: 1/8
3: 1/8T
4: 1/8 + 1/8T
5: 1/16
6: 1/16T
7: 1/16 + 1/16T
8:1/32
nudge_down bool get, set, observe The status (1=pressed) of the nudge down button in the transport bar.
nudge_up bool get, set, observe The status (1=pressed) of the nudge up button in the transport bar.
overdub bool get, set, observe 1=overdub flag in transport bar is highlighted.
punch_in bool get, set, observe 1=the punch in switch in transport is highlighted.
punch_out bool get, set, observe 1=the punch out switch in transport is highlighted.
record_mode bool get, set, observe 1=global record is enabled (record switch in transport is red).
select_on_launch bool get Current status (1=set) of the respective option set in the launch preferences.
signature_denominator int get, set, observe
signature_numerator int get, set, observe
song_length float get, observe A little more than last_event_time, in beats.
tempo float get, set, observe Current tempo of the Live set in bpm, 20.0 ... 999.0. The tempo may be automated, so it can change depending on the current song time.

Functions

Name Description
continue_playing From the current playback position.
get_beats_loop_length Returns: bars.beats.sixteenths.ticks [symbol]
The arranger loop length.
get_beats_loop_start Returns: bars.beats.sixteenths.ticks [symbol]
The arranger loop start.
get_current_beats_song_time Returns: bars.beats.sixteenths.ticks [symbol]
The current arranger playback position.
get_current_smpte_song_time Parameter: format
format [int] is the time code type to be returned
0: the frames position shows the milliseconds
1: Smpte24
2: Smpte25
3: Smpte30
4: Smpte30Drop
5: Smpte29
Returns: hours:min:sec:frames [symbol]
The current arranger playback position.
is_cue_point_selected Returns: bool 1=the current arranger playback position is at a cue point
jump_by Parameter: beats
beats [double] is the amount to jump relatively to the current position
jump_to_next_cue Jumps to the right, if possible.
jump_to_prev_cue Jumps to the left, if possible.
play_selection Does nothing if no selection is set in arranger.
redo Causes the Live application to redo the last operation.
scrub_by Parameter: beats
beats [double] the amount to scrub relative to the current arranger playback position
Same as jump_by, at the moment.
set_or_delete_cue Toggle cue point at current arranger playback position.
start_playing
stop_all_clips
stop_playing
tap_tempo Same as tapping the tempo field in the transport bar. The new tempo is calculated based on the time between subsequent calls of this function.
undo Causes the Live application to undo the last operation.

Song.View

This class represents the view aspects of a Live document: the session and arranger views.

Canonical path

live_set view

Children

Name Type Access Description
detail_clip Clip get, set, observe The clip currently displayed in the Live applications detail view.
highlighted_clip_slot ClipSlot get, set The slot highlighted in the session view.
selected_parameter DeviceParameter get, observe The selected parameter, or "id 0"
selected_scene Scene get, set, observe
selected_track Track get, set, observe

Properties

Name Type Access Description
draw_mode bool get, set, observe Reflects the state of the envelope/automation draw mode switch in transport bar, as toggled with Cmd/Ctrl-B.
0=breakpoint editing (shows arrow), 1=drawing (shows pencil)
follow_song bool get, set, observe Reflects the state of the follow switch in transport bar as toggled with Cmd/Ctrl-F.
0=don't follow playback position, 1=follow playback position

Functions

Name Description
select_device Parameter: id NN
Selects the given device object in its track.
You may obtain the id using a live.path or by using get devices on a track, for example.
The track containing the device will not be shown automatically, and the device gets the appointed device (blue hand) only if its track is selected.

Track

This class represents a track in Live. It can be either an audio track, a MIDI track, a return track or the master track. The master track and at least one Audio or MIDI track will be always present. Return tracks are optional.

Not all properties are supported by all types of tracks. The properties are marked accordingly.

Canonical path

live_set tracks N

Children

Name Type Access Description
clip_slots list of ClipSlot get, observe
devices list of Device get, observe Includes mixer device.
mixer_device MixerDevice get
view Track.View get

Properties

Name Type Access Description
arm bool get, set, observe 1=track is armed for recording. [not in return/master tracks]
can_be_armed bool get Is 0 for return and master tracks.
current_input_routing symbol get, set, observe As all other routings, reflects the string shown in the routing selector.
current_input_sub_routing symbol get, set, observe Doesn't send any output if the selector has no entries.
current_monitoring_state int get, set, observe 0=In 1=Auto 2=Off [not in return/master tracks]
current_output_routing symbol get, set, observe
current_output_sub_routing symbol get, set, observe Doesn't send any output if the selector has no entries.
fired_slot_index int get, observe Reflects the blinking clip slot.
-1=no slot fired, -2=track stop button fired
First clip slot has index 0.
[not in return/master tracks]
fold_state int get, set 0=subtracks are visible 1=track is folded and subtracks hidden
[only available if is_foldable is 1]
has_audio_input bool get 1 for audio tracks.
has_audio_output bool get 1 for audio tracks and MIDI tracks with instrument.
has_midi_input bool get 1 for MIDI tracks.
has_midi_output bool get 1 for MIDI tracks with no instruments and no audio effects.
input_meter_level float get, observe Hold peak value of input meters of audio and MIDI tracks, 0.0 ... 1.0. For audio tracks it is the maximum of the left and right channels. The hold time is 1 second.
input_meter_left float get, observe Smoothed momentary peak value of left channel input meter, 0.0 to 1.0. For tracks with audio output only. This value corresponds to the meters shown in Live. Please take into account that the left/right audio meters put a significant load onto the GUI part of Live.
input_meter_right float get, observe Smoothed momentary peak value of right channel input meter, 0.0 to 1.0. For tracks with audio output only. This value corresponds to the meters shown in Live.
input_routings list of symbols get Available input routings. [not in master track]
input_sub_routings list of symbols get Available sub routings for the currently selected input routing. Does not output anything if no entries are available. [not in master track]
is_foldable bool get 1 if track can be (un)folded to hide resp. reveal the contained tracks. This is currently the case for group tracks. Instrument and drum racks return 0 although they can be openend/closed. This will be fixed in a later release.
is_part_of_selection bool get
is_visible bool get 0=track is hidden in a folded group track.
mute bool get, set, observe [not in master track]
name symbol get, set, observe As shown in track header.
output_meter_level float get, observe Hold peak value of output meters of audio and MIDI tracks, 0.0 ... 1.0. For audio tracks it is the maximum of the left and right channels. The hold time is 1 second.
output_meter_left float get, observe Smoothed momentary peak value of left channel output meter, 0.0 to 1.0. For tracks with audio output only. This value corresponds to the meters shown in Live. Please take into account that the left/right audio meters put a significant load onto the GUI part of Live.
output_meter_right float get, observe Smoothed momentary peak value of right channel output meter, 0.0 to 1.0. For tracks with audio output only. This value corresponds to the meters shown in Live.
output_routings list of symbols get Available output routings. [not in master track]
output_sub_routings list of symbols get Available sub routings for the currently selected output routing. Does not output anything if no entries are available. [not in master track]
playing_slot_index int get, observe First slot has index 0, -1=no clip playing. [not in return/master tracks]
solo bool get, set, observe Remark: when setting this property, the exclusive solo logic is bypassed, so you have to unsolo the other tracks yourself. [not in master track]

Functions

Name Description
jump_in_running_session_clip Parameter: beats
beats [double] is the amount to jump relatively to the current clip position.
Modify playback position in running session clip, if any.
stop_all_clips Stops all playing and fired clips in this track.

Track.View

Representing the view aspects of a Track.

Canonical path

live_set tracks N view

Children

Name Type Access Description
selected_device Device get, observe The selected device or, in case of multi/group selection, the first selected device.

Properties

Name Type Access Description
is_collapsed bool get, set, observe In arranger view: 1=track collapsed, 0=track opened.

Functions

Name Description
select_instrument Returns: bool 0=there are no devices to select
Selects track instrument or first device, makes it visible and focuses on it.

ClipSlot

This class represents an entry in Lives Session view matrix.

The properties playing_status, is_playing and is_recording are useful for clip slots of group tracks. These are always empty and represent the state of the clips in their subtracks.

Canonical path

live_set tracks N clip_slots M

Children

Name Type Access Description
clip Clip get id 0 if slot is empty

Properties

Name Type Access Description
controls_other_clips bool get, observe 1 for a group track slot that has non-deactivated clips in substracks.
Control of empty clip slots doesn't count.
has_clip bool get, observe
has_stop_button bool get, set, observe If 1, this clip stops its track (or subtracks).
playing_status int get, observe 0=all clips in subtracks stopped or all empty subtracks.
1=at least one clip in subtracks playing.
2= at least one clip in subtracks playing or recording.
Equals 0 if this is not a clip slot of a group track.
is_playing bool get For group tracks: 1 if playing_status != 0, otherwise 0.
For non-group tracks: 0 if empty, otherwise not available.
is_recording bool get For group tracks: 1 if playing_status == 2, otherwise 0.
For non-group tracks: 0 if empty, otherwise not available.
is_triggered bool get, observe 1=clip slot button (start, stop or record) or button of contained clip are blinking.
will_record_on_start bool get 1=clip slot will record on start.

Functions

Name Description
fire Fires the clip or triggers the stop button, if any. Starts recording if slot is empty and track is armed. Starts recording of armed and empty subtracks if Preferences->Launch->Start Recording on Scene Launch is ON.
set_fire_button_state Parameter: state
state [bool]
If the state is set to 1, Live simulates pressing of slot start button until the state is set to 0 or until the slot is stopped otherwise.
stop Stops playing or recording clips in this track or its subtracks, if any. It doesn't matter on which slot of the track you call this function.

Clip

This class represents a clip in Live. It can be either an audio clip or a MIDI clip in an arrangement or the session depending on the track (slot) it lives in.

Canonical path

live_set tracks N clip_slots M clip

Properties

Name Type Access Description
color int get, set, observe The RGB value of the clip's color in the form 0x00rrggbb or (2^16 * red) + (2^8) * green + blue, where red, green and blue are values from 0 (dark) to 255 (light).

When setting the RGB value, the nearest color from the Clip color chooser is taken.
is_audio_clip bool get 0=MIDI clip, 1=audio clip
is_midi_clip bool get The opposite of is_audio_clip.
is_playing bool get, set 1 if clip is playing or recording.
is_recording bool get, observe 1 if clip is recording.
is_triggered bool get 1 if play button is blinking.
playing_status bang observe Observer sends bang when playing/trigger status changes.
length double get For looped clips: loop length in beats. Otherwise its the distance in beats from start to stop marker. Makes no sense for unwarped audio clips.
loop_start double get, set, observe For looped clips: loop start.
For unlooped clips: clip start.

loop_start and loop_end are in absolute clip beat time of clip is MIDI or warped. The 1.1.1 position has beat time 0. If the clip is unwarped audio, they are given in seconds, 0 is the time of the first sample in the audio material.
loop_end double get, set, observe For looped clips: loop end.
For unlooped clips: clip end.
loop_jump bang observe Bangs when the clip play position is crossing the loop start marker (possibly projected into the loop).
looping bool get, set, observe 1 if clip is looped. Unwarped audio cannot be looped.
muted bool get, set, observe 1 if muted (i.e. power button of the clip is off).
name symbol get, set, observe
pitch_coarse int get, set, observe Pitch shift in semitones ("Transpose"), -48 ... 48.
Available for audio clips only.
pitch_fine float get, set, observe Extra pitch shift in cents ("Detune"), -50 ... 49.
Available for audio clips only.
playing_position float get, observe Current playing position of the clip.

For MIDI and warped audio clips the value is given in beats of absolute clip time. Zero beat time of the clip is where 1 is shown in the bar/beat/16th time scale at the top of the clip view.

For unwarped audio clips, the position is given in seconds, according to the time scale shown at the bottom of the clip view.

Stopped clips have a playing position of 0.
notes bang observe Observer sends bang when notelist changes.
Available for MIDI clips only.
signature_denominator int get, set, observe
signature_numerator int get, set, observe
warping bool get, set, observe 1 if warp switch is on.
Available for audio clips only.
will_record_on_start bool get 1 for MIDI clips which are in triggered state, with the track armed and overdub on.

Functions

Name Description
fire Same effect as pressing the start button of the clip.
move_playing_pos Parameter: beats
beats [double] relative jump distance in beats. Negative beats jump backwards.
Jumps by given amount, unquantized.
Unwarped audio clips, recording audio clips and recording non-overdub MIDI clips cannot jump.
set_fire_button_state Parameter: state
state [bool]
If the state is set to 1, Live simulates pressing of clip start button until the state is set to 0 or until the clip is stopped otherwise.
stop Same effect as pressing the stop button of the track, but only if this clip is actually playing or recording. It has no effect if this clip is triggered or if another clip in this track is playing.
deselect_all_notes Call this before replace_selected_notes if you just want to add some notes.
Output:
deselect_all_notes id 0

For MIDI clips only.
get_selected_notes Use this if you want to operate on the selected notes.
Output:
get_selected_notes notes count
get_selected_notes note pitch time duration velocity muted
...
get_selected_notes done

count [int] is the number of note lines to follow.
pitch [int] is the MIDI note number, 0...127, 60 is C3.
time [double] is the note start time in beats of absolute clip time.
duration [double] is the note length in beats.
velocity [int] is the note velocity, 1 ... 127.
muted [bool] is 1 if the note is deactivated.

For MIDI clips only.
replace_selected_notes To replace the notes selected in the clip, send a series of the following function calls to the Clip.

replace_selected_notes
notes count
note pitch time duration velocity muted
done

The sequence is the same as in get_selected_notes, the parameters are the same too. The sequence must always be completed, the clip waits for the respective calls even if intermediate messages are sent. If count is zero, there are no note calls, obviously.

In Live, notes don't overlap, so if the new notes overlap with unselected notes, the unselected ones are made to fit just like it works when you edit notes manually

An example sequence of calls looks like this:

call replace_selected_notes
call notes 2
call note 60 0.0 0.5 100 0
call note 62 0.5 0.5 64 0
call done

For MIDI clips only.
select_all_notes Use this function, for example, to process all notes of a clip, independently of the current selection.

Output:
select_all_notes id 0

For MIDI clips only.

Device

This class represents a MIDI or audio device in Live.

Canonical path

live_set tracks N devices M

Canonical path

live_set tracks N devices M chains L devices K

Canonical path

live_set tracks N devices M return_chains L devices K

Children

Name Type Access Description
parameters list of DeviceParameter get, observe Only automatable parameters are accessible. See DeviceParameter to learn how to modify them.
chains list of Chain get, observe available for device Racks only
return_chains list of Chain get, observe available for device Racks only

Properties

Name Type Access Description
class_name symbol get Live device type such as MidiChord, Operator, Limiter, MxDeviceAudioEffect, or PluginDevice.
name symbol get, set, observe This is the string shown in the title bar of the device.
can_have_chains bool get 0 for a single device
1 for a device Rack

Functions

Name Description
store_chosen_bank Parameters: script_index bank_index
script_index [int]
bank_index [int]
(This is related to hardware control surfaces and is usually not relevant.)

Chain

This class represents a group device chain in Live.

Canonical path

live_set tracks N devices M chains L

Canonical path

live_set tracks N devices M return_chains L

Canonical path

live_set tracks N devices M chains L devices K chains P ...

Canonical path

live_set tracks N devices M return_chains L devices K chains P ...

Children

Name Type Access Description
devices Device get, observe
mixer_device ChainMixerDevice get

Properties

Name Type Access Description
mute bool get, set, observe 1 = muted (chain activator off)
name unicode get, set, observe
solo bool get, set, observe 1 = soloed (solo switch on)
does not automatically turn solo off in other chains.

ChainMixerDevice

This class represents a chain's mixer device in Live.

Canonical path

live_set tracks N devices M chains L mixer_device

Canonical path

live_set tracks N devices M return_chains L mixer_device

Children

Name Type Access Description
sends list of DeviceParameter get, observe [in audio- and instrument racks only]
for Drum Racks, otherwise empty
panning DeviceParameter get [in audio- and instrument racks only]
volume DeviceParameter get [in audio- and instrument racks only]
chain_activator DeviceParameter get

DeviceParameter

This class represents an (automatable) parameter within a MIDI or audio device. To modify a device parameter, set its value property or send its object id to live.remote~.

Canonical path

live_set tracks N devices M parameters L

Properties

Name Type Access Description
default_value float get Applied when you press the delete key.
is_enabled bool get 1 if the parameter value can be modified directly by the user, by sending set to a live.object, by automation or by an assigned MIDI message or keystroke.
Parameters can be disabled because they are macro-controlled, because they are controlled by a live-remote~ object, or because Live thinks that they must not be moved.
is_quantized bool get 1 for booleans and enums
0 for int/float parameters
Although parameters like MidiPitch.Pitch appear quantized to the user, they actually have an is_quantized value of 0.
max float get Lowest allowed value.
min float get Largest allowed value.
name symbol get The short parameter name as shown in the (closed) automation chooser .
original_name symbol get For macro parameters, the name before assignment.
value float get, set, observe Linear-to-GUI value between min and max.

MixerDevice

This class represents a mixer device in Live. It provides access to volume, panning and other DeviceParameter objects. See DeviceParameter to learn how to modify them.

Canonical path

live_set tracks N mixer_device

Children

Name Type Access Description
sends list of DeviceParameter get, observe One send per return track.
panning DeviceParameter get
volume DeviceParameter get
cue_volume DeviceParameter get [in master track only]
crossfader DeviceParameter get [in master track only]
track_activator DeviceParameter get
song_tempo DeviceParameter get [in master track only]

Properties

Name Type Access Description
crossfade_assign int get, set, observe 0=A, 1=none, 2=B [not in master track]

Scene

This class represents a series of clip slots in Live's session view matrix.

Canonical path

live_set scenes N

Children

Name Type Access Description
clip_slots list of ClipSlot get, observe

Properties

Name Type Access Description
color int get, set, observe The RGB value of the scene's color in the form 0x00rrggbb or (2^16 * red) + (2^8) * green + blue, where red, green and blue are values from 0 (dark) to 255 (light).

When setting the RGB value, the nearest color from the Scene color chooser is taken.
is_triggered bool get, observe 1=scene is blinking.
name symbol get, set, observe May contain bpm and signature commands (like "128bpm 3/4").
tempo float get, set Tempo in bpm as found by Live in the name.

Functions

Name Description
fire Fire all clip slots owned by the scene and select this scene.
Starts recording of armed and empty subtracks in these scene if Preferences->Launch->Start Recording on Scene Launch is ON.
fire_as_selected Fire the selected scene, then select next scene.
It doesn't matter on which scene you are calling this function.
set_fire_button_state Parameter: state
state [bool]
If the state is set to 1, Live simulates pressing of scene button until the state is set to 0 or until the scene is stopped otherwise.

CuePoint

Represents a 'marker' in the arrangement.

Canonical path

live_set cue_points N

Properties

Name Type Access Description
name symbol get, observe
time float get, observe Arranger position of the marker in beats.

Functions

Name Description
jump Set current arranger playback position to marker, quantized if song is playing.

ControlSurface

The control surfaces are reachable by the root path control_surfaces N .

Canonical path

control_surfaces N

this_device

This root path represents the device containing the live.path object to which the goto this_device message is sent. The class of this object is Device.

Canonical path

live_set tracks N devices M