LOM - The Live Object Model Reference

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

Name	Type	Access	Description
view	Application.View	get

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.

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

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

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.)

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

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.

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.

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]

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.