Objects which comprise the Live API described by their structure, properties and functions.
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 9.7.3
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
Children
Properties
current_dialog_button_count
Description
The number of buttons in the current message box.
current_dialog_message
Description
The text of the current message box (empty if no message box is currently shown).
Functions
get_bugfix_version
Returns: the 2 in Live 9.1.2.
get_document
Returns: the current Live Set.
get_major_version
Returns: the 9 in Live 9.1.2.
get_minor_version
Returns: the 1 in Live 9.1.2.
press_current_dialog_button
Parameter:
index
Press the button with the given index in the current dialog box.
Application.View
This class represents the aspects of the Live application related to viewing the application.
Canonical path
Children
Properties
focused_document_view
Description
The name of the currently visible view in the focused Live window ('Session' or 'Arranger').
Functions
available_main_views
Returns:
view names
[list of symbols].
This is a constant list of view names to be used
as an argument when calling other functions:
Browser Arranger Session Detail Detail/Clip Detail/DeviceChain
.
focus_view
Parameter:
view_name
Shows named view and focuses on it. You can also pass an empty view_name “ ", which refers to the Arrangement or Session View (whichever is visible in the main window).
hide_view
Parameter:
view_name
Hides the named view. You can also pass an empty view_name “ ", which refers to the Arrangement or Session View (whichever is visible in the main window).
is_view_visible
Parameter:
view_name
Returns: [bool] Whether the specified view is currently visible.
scroll_view
Parameters:
direction view_name modifier_pressed
direction
[int] is 0 = up, 1 = down, 2 = left, 3 = right
modifier_pressed
[bool] If view_name is "Arranger" and modifier_pressed is 1 and direction is left or right, then the size of the selected time region is modified, otherwise the position of the playback cursor is moved.
Not all views are scrollable, and not in all directions. Currently, only the
Arranger
,
Browser
,
Session
, and
Detail/DeviceChain
views can be scrolled.
You can also pass an empty view_name
" "
, which refers to the Arrangement or Session View (whichever view is
visible).
show_view
Parameter: view_name
toggle_browse
Displays the device chain and the browser and activates Hot-Swap Mode for the selected device. Calling this function again deactivates Hot-Swap Mode.
zoom_view
Parameter:
direction view_name modifier_pressed
direction
[int] - 0 = up, 1 = down, 2 = left, 3 = right
modifier_pressed
[bool] If view_name is 'Arrangement', modifier_pressed is 1, and direction is left or right, then the size of the selected time region is modified, otherwise the position of the playback cursor is moved. If view_name is Arrangement and modifier_pressed is 1 and direction is up or down, then only the height of the highlighted track is changed, otherwise the height of all tracks is changed.
Only the Arrangement and Session Views can be zoomed. For Session View, the behaviour of zoom_view is identical to scroll_view.
You can also pass an empty view_name “ ", which refers to the Arrangement or Session View (whichever is visible in the main window).
Song
This class represents a Live Set. The current Live Set is reachable by the root path live_set .
Canonical path
Children
cue_points
Description
Cue points are the markers in the Arrangement to which you can jump.
visible_tracks
Description
A track is visible if it's not part of a folded group. If a track is scrolled out of view it's still considered visible.
Properties
appointed_device
Description
The appointed device is the one used by a control surface unless the control surface itself chooses which device to use. It is marked by a blue hand.
arrangement_overdub
Description
Get/set the state of the MIDI Arrangement Overdub button.
back_to_arranger
Description
Get/set the current state of the Back to Arrangement button located in Live'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
Description
0 = there is no cue point to the right of the current one, or none at all.
can_jump_to_prev_cue
Description
0 = there is no cue point to the left of the current one, or none at all.
clip_trigger_quantization
Description
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
count_in_duration
Description
The duration of the Metronome's Count-In setting as an index, mapped as follows:
0 = None
1 = 1 Bar
2 = 2 Bars
3 = 4 Bars
current_song_time
Description
The playing position in the Live Set, in beats.
exclusive_arm
Description
Current status of the exclusive Arm option set in the Live preferences.
exclusive_solo
Description
Current status of the exclusive Solo option set in the Live preferences.
groove_amount
Description
The groove amount from the current Set's Groove Pool (0. - 1.0).
last_event_time
Description
The beat time of the last event (i.e. automation breakpoint, clip end, cue point, loop end) in the Arrangement.
loop
Description
Get/set the enabled state of the Arrangement loop.
midi_recording_quantization
Description
Get/set the current Record Quantization value.
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
Description
1 = the Tempo Nudge Down button in the transport bar is currently pressed.
nudge_up
Description
1 = the Tempo Nudge Up button in the transport bar is currently pressed.
overdub
Description
1 = MIDI Arrangement Overdub is enabled in the transport.
punch_in
Description
1 = the Punch-In button is enabled in the transport.
punch_out
Description
1 = the Punch-Out button is enabled in the transport.
re_enable_automation_enabled
Description
1 = the Re-Enable Automation button is on.
root_note
Description
The root note of the song used for control surfaces. The root note can be a number between 0 and 11, where 0 = C and 11 = B.
scale_name
Description
The last used scale name used for control surfaces. The default scale names that can be saved with a Live Set are:
'Major'
'Minor'
'Dorian'
'Mixolydian'
'Lydian'
'Phrygian'
'Locrian'
'Diminished'
'Whole-half'
'Whole Tone'
'Minor Blues'
'Minor Pentatonic'
'Major Pentatonic'
'Harmonic Minor'
'Melodic Minor'
'Super Locrian'
'Bhairav'
'Hungarian Minor'
'Minor Gypsy'
'Hirojoshi'
'In-Sen'
'Iwato'
'Kumoi'
'Pelog'
'Spanish'
select_on_launch
Description
1 = the "Select on Launch" option is set in Live's preferences.
session_automation_record
Description
The state of the Automation Arm button.
session_record
Description
The state of the Session Overdub button.
session_record_status
Description
Reflects the state of the Session Record button.
swing_amount
Description
Range: 0.0 - 1.0; affects MIDI Recording Quantization and all direct calls to Clip.quantize.
tempo
Description
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
capture_and_insert_scene
Capture the currently playing clips and insert them as a new scene below the selected scene.
continue_playing
From the current playback position.
create_audio_track
Parameter:
index
Index determines where the track is added, it is only valid between 0 and
len(song.tracks). Using an index of -1 will add the new track at the end of the list.
create_midi_track
Parameter:
index
Index determines where the track is added, it is only valid between 0 and
len(song.tracks). Using an index of -1 will add the new track at the end of the list.
create_return_track
Adds a new return track at the end.
create_scene
Parameter:
index
Returns: The new scene
Index determines where the scene is added. It is only valid between 0 and
len(song.scenes). Using an index of -1 will add the new scene at the end of the list.
delete_scene
Parameter:
index
Delete the scene at the given index.
delete_track
Parameter:
index
Delete the track at the given index.
delete_return_track
Parameter:
index
Delete the return track at the given index.
duplicate_scene
Parameter:
index
Index determines which scene to duplicate.
duplicate_track
Parameter:
index
Index determines which track to duplicate.
find_device_position
Parameter:
device [live object]
target [live object]
target position [int]
Returns:
[int] The position in the target's chain where the device can be
inserted that is the closest possible to the target position.
force_link_beat_time
Force the Link timeline to jump to Live's current beat time.
get_beats_loop_length
Returns:
bars.beats.sixteenths.ticks
[symbol]
The Arrangement loop length.
get_beats_loop_start
Returns:
bars.beats.sixteenths.ticks
[symbol]
The Arrangement loop start.
get_current_beats_song_time
Returns:
bars.beats.sixteenths.ticks
[symbol]
The current Arrangement playback position.
get_current_smpte_song_time
Parameter:
format
format
[int] is the time code type to be returned
0 = the frame position shows the milliseconds
1 = Smpte24
2 = Smpte25
3 = Smpte30
4 = Smpte30Drop
5 = Smpte29
Returns:
hours:min:sec:frames
[symbol]
The current Arrangement playback position.
is_cue_point_selected
Returns: bool 1 = the current Arrangement 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
Jump to the right, if possible.
jump_to_prev_cue
Jump to the left, if possible.
move_device
Parameter:
device [live object]
target [live object]
target position [int]
Returns: [int] The position in the target's chain where the device was inserted.
Move the device to the specified position in the target chain. If the device cannot be moved to the specified position, the nearest possible
position is chosen.
play_selection
Do nothing if no selection is set in Arrangement, or play the current selection.
re_enable_automation
Trigger 'Re-Enable Automation', re-activating automation in all running Session clips.
redo
Causes the Live application to redo the last operation.
scrub_by
Parameter:
beats
beats
[double] the amount to scrub relative to the current Arrangement
playback position
Same as
jump_by
, at the moment.
set_or_delete_cue
Toggle cue point at current Arrangement playback position.
start_playing
Start playback from the insert marker.
stop_all_clips
Parameter (optional):
quantized
Calling the function with 0 will stop all clips immediately, independent of
the launch quantization. The default is '1'.
stop_playing
Stop the playback.
tap_tempo
Same as pressing the Tap Tempo button in the transport bar. The new tempo is calculated based on the time between subsequent calls of this function.
trigger_session_record
Parameter:
record_length (optional)
Starts recording in either the selected slot or the next empty slot, if the track
is armed. If record_length is provided, the slot will record for the
given length in beats.
If triggered while recording, recording will stop and clip playback will start.
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 Arrangement Views.
Canonical path
Children
detail_clip
Description
The clip currently displayed in the Live application's Detail View.
highlighted_clip_slot
Description
The slot highlighted in the Session View.
selected_parameter
Description
The selected parameter, or "id 0"
Properties
draw_mode
Description
Reflects the state of the envelope/automation Draw Mode Switch in the
transport bar, as toggled with Cmd/Ctrl-B.
0 = breakpoint editing (shows arrow), 1 = drawing (shows pencil)
follow_song
Description
Reflects the state of the Follow switch in the transport bar as toggled
with Cmd/Ctrl-F.
0 = don't follow playback position, 1 = follow playback position
Functions
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 either be 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
Children
Properties
arm
Description
1 = track is armed for recording. [not in return/master tracks]
available_input_routing_channels
Description
The list of available source channels for the track's input routing.
It's represented as a dictionary with the following key:
available_input_routing_channels [list]
The list contains dictionaries as described in input_routing_channel.
Only available on MIDI and audio tracks.
available_input_routing_types
Description
The list of available source types for the track's input routing.
It's represented as a dictionary with the following key:
available_input_routing_types [list]
The list contains dictionaries as described in input_routing_type.
Only available on MIDI and audio tracks.
available_output_routing_channels
Description
The list of available target channels for the track's output routing.
It's represented as a dictionary with the following key:
available_output_routing_channels [list]
The list contains dictionaries as described in output_routing_channel.
Not available on the master track.
available_output_routing_types
Description
The list of available target types for the track's output routing.
It's represented as a dictionary with the following key:
available_output_routing_types [list]
The list contains dictionaries as described in output_routing_type.
Not available on the master track.
can_show_chains
Description
1 = the track contains an Instrument Rack device that can show chains in Session View.
color
Description
The RGB value of the track'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 track color
chooser is taken.
current_input_routing
Description
Like all other routings, reflects the string shown in the routing selector.
Deprecated since Live 9.7. Please use input_routing_type instead.
current_input_sub_routing
Description
Doesn't send any output if the selector has no entries.
Deprecated since Live 9.7. Please use input_routing_channel instead.
current_monitoring_state
Description
0 = In, 1 = Auto, 2 = Off [not in return/master tracks]
current_output_routing
Description
Deprecated since Live 9.7. Please use output_routing_type instead.
current_output_sub_routing
Description
Doesn't send any output if the selector has no entries.
Deprecated since Live 9.7. Please use output_routing_channel instead.
fired_slot_index
Description
Reflects the blinking clip slot.
-1 = no slot fired, -2 = Clip Stop Button fired
First clip slot has index 0.
[not in return/master tracks]
fold_state
Description
0 = tracks within the Group Track are visible, 1 = Group Track is folded and the tracks within the Group Track are hidden
[only available if
is_foldable
= 1]
has_audio_output
Description
1 for audio tracks and MIDI tracks with instruments.
has_midi_output
Description
1 for MIDI tracks with no instruments and no audio effects.
implicit_arm
Description
A second arm state, only used by Push so far.
input_meter_left
Description
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_level
Description
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_right
Description
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_routing_channel
Description
The currently selected source channel for the track's input routing.
It's represented as a dictionary with the following keys:
display_name [symbol]
identifier [symbol]
Can be set to all values found in the track's available_input_routing_channels.
Only available on MIDI and audio tracks.
input_routing_type
Description
The currently selected source type for the track's input routing.
It's represented as a dictionary with the following keys:
display_name [symbol]
identifier [symbol]
Can be set to all values found in the track's available_input_routing_types.
Only available on MIDI and audio tracks.
input_routings
Description
Available input routings. [not in master track]
Deprecated since Live 9.7. Please use available_input_routing_types instead.
input_sub_routings
Description
Available sub routings for the currently selected input routing.
If no entries are available, nothing is output. [not in master track]
Deprecated since Live 9.7. Please use available_input_routing_channels instead.
is_foldable
Description
1 = track can be (un)folded to hide or reveal the contained tracks. This is currently the case for Group Tracks. Instrument and Drum Racks return 0 although they can be opened/closed. This will be fixed in a later release.
is_showing_chains
Description
Get or set whether a track with an Instrument Rack device is currently showing its chains in Session View.
muted_via_solo
Description
1 = the track or chain is muted due to Solo being active on at least one other track.
output_meter_left
Description
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 add a significant load to Live GUI resource usage.
output_meter_level
Description
Hold peak value of output meters of audio and MIDI tracks, 0.0 to 1.0. For audio tracks, it is the maximum of the left and right channels. The hold time is 1 second.
output_meter_right
Description
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_routing_channel
Description
The currently selected target channel for the track's output routing.
It's represented as a dictionary with the following keys:
display_name [symbol]
identifier [symbol]
Can be set to all values found in the track's available_output_routing_channels.
Not available on the master track.
output_routing_type
Description
The currently selected target type for the track's output routing.
It's represented as a dictionary with the following keys:
display_name [symbol]
identifier [symbol]
Can be set to all values found in the track's available_output_routing_types.
Not available on the master track.
output_routings
Description
Available output routings. [not in master track]
Deprecated since Live 9.7. Please use available_output_routing_types instead.
output_sub_routings
Description
Available sub routings for the currently selected output routing.
If no entries are available, nothing is output. [not in master track]
Deprecated since Live 9.7. Please use available_output_routing_channels instead.
playing_slot_index
Description
First slot has index 0, -2 = Clip Stop slot fired in Session View, -1 = Arrangement recording with no Session clip playing. [not in return/master tracks]
solo
Description
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
delete_clip
Parameter:
clip
Delete the given clip.
delete_device
Parameter:
index
Delete the device at the given index.
duplicate_clip_slot
Parameter:
index
Works like 'Duplicate' in a clip's context menu.
duplicate_clip_to_arrangement
Parameters:
clip
destination_time
[double]
Duplicate the given clip to the Arrangement, placing it at the given destination_time in beats.
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
Children
selected_device
Description
The selected device or the first selected device (in case of multi/group selection).
Properties
device_insert_mode
Description
Determines where a device will be inserted when loaded from the browser. 0 = add device at the end, 1 = add device to the left of the selected device, 2 = add device to the right of the selected device.
is_collapsed
Description
In Arrangement View: 1 = track collapsed, 0 = track opened.
Functions
select_instrument
Returns: bool 0 = there are no devices to select
Selects track's instrument or first device, makes it visible and
focuses on it.
ClipSlot
This class represents an entry in Live's 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 the tracks within the Group Track.
Canonical path
Children
Properties
color
Description
The color of the first clip in the Group Track if the clip slot is a Group Track slot.
color_index
Description
The color index of the first clip in the Group Track if the clip slot is a Group Track slot.
controls_other_clips
Description
1 for a Group Track slot that has non-deactivated clips in the tracks
within its group.
Control of empty clip slots doesn't count.
has_stop_button
Description
1 = this clip stops its track (or tracks within a Group Track).
is_triggered
Description
1 = clip slot button (Clip Launch, Clip Stop or Clip Record) or button of contained clip are blinking.
playing_status
Description
0 = all clips in tracks within a Group Track stopped or all tracks within a Group Track are empty.
1 = at least one clip in a track within a Group Track is playing.
2 = at least one clip in a track within a Group Track is playing or recording.
Equals 0 if this is not a clip slot of a Group Track.
Functions
create_clip
Parameter:
length
Length is given in beats and must be a greater value than 0.0. Can only be called on empty
clip slots in MIDI tracks.
delete_clip
Deletes the contained clip.
duplicate_clip_to
Parameter: target_clip_slot [ClipSlot]
Duplicates the slot's clip to the given clip slot, overriding the target clip slot's clip if it's not empty.
fire
Parameter:
record_length (optional)
launch_quantization (optional)
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 tracks within a Group Track if Preferences->Launch->Start Recording on Scene
Launch is ON. If record_length is provided, the slot will record for the
given length in beats. launch_quantization overrides the global quantization
if provided.
set_fire_button_state
Parameter:
state
[bool]
1 = Live simulates pressing of Clip Launch
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 the tracks within the group, 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 the Arrangement or Session View, depending on the track / slot it lives in.
Canonical path
Children
Properties
available_warp_modes
Description
Returns the list of indexes of the Warp Modes available for the clip. Only valid for audio clips.
color
Description
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.
end_marker
Description
The end marker of the clip in beats, independent of the loop state. Cannot be set before the start marker.
end_time
Description
The end time of the clip. For Session View clips, if Loop is on, this is the Loop End, otherwise it's the End Marker. For Arrangement View clips, this is always the position of the clip's rightmost edge in the Arrangement.
gain
Description
The gain of the clip (range is 0.0 to 1.0). Only valid for audio clips.
gain_display_string
Description
Get the gain display value of the clip as a string (e.g. "1.3 dB"). Can only be called on audio clips.
file_path
Description
Get the location of the audio file represented by the clip. Only available for audio clips.
has_envelopes
Description
Get/observe whether the clip has any automation.
is_arrangement_clip
Description
1 = The clip is an Arrangement clip.
A clip can be either an Arrangement or a Session clip.
length
Description
For looped clips: loop length in beats. Otherwise it's the distance in beats from start to end marker. Makes no sense for unwarped audio clips.
loop_end
Description
For looped clips: loop end.
For unlooped clips: clip end.
loop_jump
Description
Bangs when the clip play position is crossing the loop start marker (possibly projected into the loop).
loop_start
Description
For looped clips: loop start.
For unlooped clips: clip start.
loop_start and loop_end are in absolute clip beat time if 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.
looping
Description
1 = clip is looped. Unwarped audio cannot be looped.
muted
Description
1 = muted (i.e. the Clip Activator button of the clip is off).
notes
Description
Observer sends bang when the list of notes changes.
Available for MIDI clips only.
pitch_coarse
Description
Pitch shift in semitones ("Transpose"), -48 ... 48.
Available for audio clips only.
pitch_fine
Description
Extra pitch shift in cents ("Detune"), -50 ... 49.
Available for audio clips only.
playing_position
Description
Get and set the clip's loop position. The value will always equal loop_start, however setting this property, unlike setting loop_start, preserves the loop length.
playing_status
Description
Observer sends bang when playing/trigger status changes.
position
Description
Current playing position of the clip.
For MIDI and warped audio clips, the value is given in beats of
absolute clip time. The clip's beat time of 0 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.
start_marker
Description
The start marker of the clip in beats, independent of the loop state. Cannot be set behind the end marker.
start_time
Description
The time the clip was started, relative to the global song time. The value is in beats.
warp_mode
Description
The Warp Mode of the clip as an integer index. Available Warp Modes are:
0 = Beats Mode
1 = Tones Mode
2 = Texture Mode
3 = Re-Pitch Mode
4 = Complex Mode
5 = REX Mode
6 = Complex Pro Mode
Available for audio clips only.
warping
Description
1 = Warp switch is on.
Available for audio clips only.
will_record_on_start
Description
1 for MIDI clips which are in triggered state, with the track armed and MIDI Arrangement Overdub on.
Functions
clear_all_envelopes
Removes all automation in the clip.
clear_envelope
Parameter:
device_parameter [id]
Removes the automation of the clip for the given parameter.
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.
duplicate_loop
Makes the loop two times longer by moving loop_end to the right, and duplicates both the notes and the envelopes. If the clip is not looped, the clip start/end range is duplicated. Available for MIDI clips only.
duplicate_region
Parameter:
region_start [double/int]
region_length [double/int]
destination_time [double/int]
pitch (optional) [int]
transposition_amount (optional) [int]
Duplicate the notes in the specified region to the destination_time.
Only notes of the specified pitch are duplicated or all if pitch is -1.
If the transposition_amount is not 0, the notes in the region will
be transposed by the transpose_amount of semitones.
Available for MIDI clips only.
fire
Same effect as pressing the Clip Launch button.
get_notes
Parameter:
from_time [double/int]
from_pitch [int]
time_span [double/int]
pitch_span [int]
Returns a list of notes that start in the given area. The output is
similar to get_selected_notes.
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] 1 = the note is deactivated.
For MIDI clips only.
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.
quantize
Parameter:
quantization_grid [int]
amount [double]
Quantizes all notes in the clip to the quantization_grid taking the song's
swing_amount into account.
quantize_pitch
Parameter:
pitch [int]
quantization_grid [int]
amount [double]
Same as quantize, but only for notes in the given pitch.
remove_notes
Parameter:
from_time [double]
from_pitch [int]
time_span [double]
pitch_span [int]
Deletes all notes that start in the given area.
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, since the clip waits for the respective calls even if
intermediate messages are sent. If count is zero, this means there are no note
calls.
In Live, notes don't overlap, so if the new notes overlap with
unselected notes, the unselected ones are made to fit in the same way as
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.
scrub
Parameter:
beat_time
[double]
Scrub the clip to a time, specified in beats. This behaves exactly like scrubbing with the mouse; the scrub will respect Global Quantization, starting and looping in time with the transport. The scrub will continue until stop_scrub() is called.
select_all_notes
Use this function to process all notes of a clip,
independent of the current selection.
Output:
select_all_notes id 0
For MIDI clips only.
set_fire_button_state
Parameter:
state
[bool]
If the state is set to 1, Live simulates pressing the clip start
button until the state is set to 0, or until the clip is otherwise stopped.
set_notes
Parameter:
list_of_notes [pitch, time, duration, velocity, is_muted]
Will apply the given notes to the clip, overwriting existing notes.
An example sequence of calls looks like this:
call set_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.
stop
Same effect as pressing the stop button of the track, but only if this clip is actually playing or recording. If this clip is triggered or if another clip in this track is playing, it has no effect.
stop_scrub
Stops an active scrub on a clip.
Clip.View
Representing the view aspects of a Clip.
Canonical path
Properties
grid_is_triplet
Description
Get/set whether the clip is displayed with a triplet grid.
Functions
hide_envelope
Hide the Envelopes box.
select_envelope_parameter
Parameter: [DeviceParameter]
Select the specified device parameter in the Envelopes box.
show_envelope
Show the Envelopes box.
show_loop
If the clip is visible in Live's Detail View, this function will make the current loop visible there.
Device
This class represents a MIDI or audio device in Live.
Canonical path
Canonical path
Canonical path
Children
parameters
Description
Only automatable parameters are accessible. See DeviceParameter to learn how to modify them.
Properties
class_display_name
Description
Get the original name of the device (e.g. Operator, Auto Filter).
class_name
Description
Live device type such as MidiChord , Operator , Limiter , MxDeviceAudioEffect , or PluginDevice .
is_active
Description
0 = either the device itself or its enclosing Rack device is off.
name
Description
This is the string shown in the title bar of the device.
type
Description
The type of the device. Possible types are: 0 = undefined, 1 = instrument, 2 = audio_effect, 3 = midi_effect.
Functions
store_chosen_bank
Parameters:
script_index
[int]
bank_index
[int]
(This is related to hardware control surfaces and is usually not
relevant.)
Device.View
Representing the view aspects of a Device.
Canonical path
Canonical path
Canonical path
Properties
is_collapsed
Description
1 = the device is shown collapsed in the device chain.
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
Properties
automation_state
Description
Get the automation state of the parameter.
0 = no automation.
1 = automation active.
2 = automation overridden.
default_value
Description
Get the default value for this parameter.
Only available for parameters that aren't quantized (see is_quantized).
is_enabled
Description
1 = 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, or they are controlled by a live-remote~ object,
or because Live thinks that they should not be moved.
is_quantized
Description
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.
name
Description
The short parameter name as shown in the (closed) automation chooser.
state
Description
The active state of the parameter.
0 = the parameter is active and can be changed.
1 = the parameter can be changed but isn't active, so changes won't have an audible effect.
2 = the parameter cannot be changed.
value_items
Description
Get a list of the possible values for this parameter.
Only available for parameters that are quantized (see is_quantized).
Functions
re_enable_automation
Re-enable automation for this parameter.
str_for_value
Parameter: value [float] Returns: [symbol] String representation of the specified value.
__str__
Returns: [symbol] String representation of the current parameter value.
RackDevice
This class represents a Live Device Rack.
A RackDevice is a type of Device, meaning that it has all the children, properties and functions that a Device has. Listed below are members unique to RackDevice.
Children
drum_pads
Description
All 128 Drum Pads for the topmost Drum Rack. Inner Drum Racks return a list of 0 entries.
visible_drum_pads
Description
All 16 visible DrumPads for the topmost Drum Rack. Inner Drum Racks return a list of 0 entries.
Properties
has_drum_pads
Description
1 = the device is a Drum Rack with pads. A nested Drum Rack is a Drum Rack without pads.
Only available for Drum Racks.
has_macro_mappings
Description
1 = any of a Rack's Macros are mapped to a parameter.
Functions
copy_pad
Parameters:
source_index
[int]
destination_index
[int]
Copies all content of a Drum Rack pad from a source pad to a destination pad.
The source_index and destination_index refer to pad indices inside a
Drum Rack.
RackDevice.View
Represents the view aspects of a Rack Device.
A RackDevice.View is a type of Device.View, meaning that it has all the properties that a Device.View has. Listed below are the members unique to RackDevice.View.
Children
selected_drum_pad
Description
Currently selected Drum Rack pad.
Only available for Drum Racks.
Properties
drum_pads_scroll_position
Description
Lowest row of pads visible, range: 0 - 28.
Only available for Drum Racks.
is_showing_chain_devices
Description
1 = the devices in the currently selected chain are visible.
DrumPad
This class represents a Drum Rack pad in Live.
Canonical path
Children
Properties
solo
Description
1 = soloed (Solo switch on)
Does not automatically turn Solo off in other chains.
Functions
delete_all_chains
Chain
This class represents a group device chain in Live.
Canonical path
Canonical path
Canonical path
Canonical path
Children
Properties
color
Description
The RGB value of the chain'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 color
chooser is taken.
is_auto_colored
Description
1 = the chain will always have the color of the containing track or chain.
solo
Description
1 = soloed (Solo switch on)
does not automatically turn Solo off in other chains.
Functions
delete_device
Parameter:
index [int]
Delete the device at the given index.
DrumChain
This class represents a Drum Rack device chain in Live.
A DrumChain is a type of Chain, meaning that it has all the children, properties and functions that a Chain has. Listed below are the members unique to DrumChain.
ChainMixerDevice
This class represents a chain's mixer device in Live.
Canonical path
Canonical path
Children
sends
Description
[in Audio Effect Racks and Instrument Racks only]
For Drum Racks, otherwise empty.
SimplerDevice
This class represents an instance of Simpler.
A Simpler device is a type of device, meaning that it has all the children, properties and functions that a device has. Listed below are members unique to SimplerDevice.
Children
Properties
pad_slicing
Description
1 = slices can be added in Slicing Mode by playing notes which are not yet assigned to existing slices.
playback_mode
Description
Get/set Simpler's playback mode.
0 = Classic Mode
1 = One-Shot Mode
2 = Slicing Mode
playing_position
Description
The current playing position in the sample, expressed as a value between 0. and 1.
playing_position_enabled
Description
1 = Simpler is playing back the sample and showing the playing position.
slicing_playback_mode
Description
Get/set Simpler's Slicing Playback Mode.
0 = Mono
1 = Poly
2 = Thru
Functions
crop
Crop the loaded sample to the active region between the start and end markers.
guess_playback_length
Returns: [float] An estimated beat time for the playback length between the start and end markers.
reverse
Reverse the loaded sample.
warp_as
Parameters: beats [int]
Warp the active region between the start and end markers as the specified number of beats.
warp_double
Double the playback tempo of the active region between the start and end markers.
warp_half
Halve the playback tempo for the active region between the start and end markers.
SimplerDevice.View
Represents the view aspects of a SimplerDevice.
A SimplerDevice.View is a type of Device.View, meaning that it has all the properties that a Device.View has. Listed below are the members unique to SimplerDevice.View.
Properties
selected_slice
Description
The currenctly selected slice, identified by its slice time.
Sample
This class represents a sample file loaded into Simpler.
Canonical path
Properties
beats_granulation_resolution
Description
Get/set which divisions to preserve in the sample in Beats Mode.
0 = 1 Bar
1 = 1/2
2 = 1/4
3 = 1/8
4 = 1/16
5 = 1/32
6 = Transients
beats_transient_envelope
Description
Get/set the duration of a volume fade applied to each segment of audio in Beats Mode.
0 = fastest decay
100 = no fade
beats_transient_loop_mode
Description
Get/set the Transient Loop Mode applied to each segment of audio in Beats Mode.
0 = Off
1 = Loop Forward
2 = Loop Back-and-Forth
complex_pro_envelope
Description
Get/set the Envelope parameter in Complex Pro Mode.
complex_pro_formants
Description
Get/set the Formants parameter in Complex Pro Mode.
end_marker
Description
Get/set the position of the sample's end marker.
slicing_sensitivity
Description
Get/set the slicing sensitivity. Values are between 0.0 and 1.0.
start_marker
Description
Get/set the position of the sample's start marker.
texture_flux
Description
Get/set the Flux parameter in Texture Mode.
texture_grain_size
Description
Get/set the Grain Size parameter in Texture Mode.
tones_grain_size
Description
Get/set the Grain Size parameter in Tones Mode.
warp_mode
Description
Get/set the Warp Mode.
0 = Beats Mode
1 = Tones Mode
2 = Texture Mode
3 = Re-Pitch Mode
4 = Complex Mode
6 = Complex Pro Mode
slicing_style
Description
Get/set the Slicing Mode.
0 = Transient
1 = Beat
2 = Region
3 = Manual
slicing_beat_division
Description
Get/set the slice beat division in Beat Slicing Mode.
0 = 1/16
1 = 1/16T
2 = 1/8
3 = 1/8T
4 = 1/4
5 = 1/4T
6 = 1/2
7 = 1/2T
8 = 1 Bar
9 = 2 Bars
10 = 4 Bars
slicing_region_count
Description
Get/set the number of slice regions in Region Slicing Mode.
Functions
gain_display_string
Returns: [list of symbols] The sample's gain value as a string, e.g. "0.0 dB".
insert_slice
Parameters: slice_time [int]
Insert a new slice at the specified time if there is none.
move_slice
Parameters: source_time [int] destination_time [int]
Move an existing slice to a specified time.
remove_slice
Parameters: slice_time [int]
Remove a slice at the specified time if it exists.
clear_slices
Clear all slices created in Manual Slicing Mode.
reset_slices
Reset all edited slices to their original positions.
PluginDevice
This class represents a plug-in device.
A PluginDevice is a type of Device, meaning that it has all the children, properties and functions that a Device has. Listed below are the members unique to PluginDevice.
Properties
selected_preset_index
Description
Get/set the index of the currently selected preset.
MaxDevice
This class represents a Max for Live device in Live.
A MaxDevice is a type of Device, meaning that it has all the children, properties and functions that a Device has. Listed below are the members unique to MaxDevice.
Functions
get_bank_count
Returns: [int] the number of parameter banks.
get_bank_name
Parameters: bank_index [int]
Returns: [list of symbols] The name of the parameter bank specified by bank_index.
get_bank_parameters
Parameters: bank_index [int]
Returns: [list of ints] The indices of the parameters contained in the bank specified by bank_index. Empty slots are marked as -1. Bank index -1 refers to the "Best of" bank.
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
Children
Properties
crossfade_assign
Description
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
Children
Properties
color
Description
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.
name
Description
May contain BPM and signature commands (like "128 BPM 3/4" ).
Functions
fire
Parameter:
force_legato (optional) [bool]
can_select_scene_on_launch (optional) [bool]
Fire all clip slots contained within the scene and select this scene.
Starts recording of armed and empty tracks within a Group Track in this scene if
Preferences->Launch->Start Recording on Scene Launch is ON.
Calling with force_legato = 1 (default = 0) will launch all clips
immediately in Legato, independent of their launch mode.
When calling with can_select_scene_on_launch = 0 (default = 1) the scene
is fired without selecting it.
fire_as_selected
Parameter:
force_legato (optional) [bool]
Fire the selected scene, then select the next scene.
It doesn't matter on which scene you are calling this function.
Calling with force_legato = 1 (default = 0) will launch all clips
immediately in Legato, independent of their launch mode.
set_fire_button_state
Parameter:
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 locator in the Arrangement View.
ControlSurface
The control surfaces are reachable by the root path
control_surfaces
N
.
Some control surfaces, such as Push, Launchpad MK2, Launchpad Pro or the Akai APC40 MkII, have some convenience methods for Live API access, which are listed below.
Canonical path
Functions
get_control
Parameter:
name
Returns the control with the given name.
get_control_names
Returns the list of all control names.
grab_control
Parameter:
control
Releases all Push functionality from the control so that it can be
used exclusively via the Live API.
release_control
Parameter:
control
Re-establishes the standard functionality for the control.
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
See Also
| Name | Description |
|---|---|
| Max For Live | Max For Live |