Song (Module)

Song (Class)

Live.Song.Song

This class represents a Live set.

Live Object: yes

Access via:

• Application.get_document()

Properties

Property	Type	Supports
appointed_device	Device \| None	get/set/listen
arrangement_overdub	bool	get/set/listen
back_to_arranger	bool	get/set/listen
can_capture_midi	bool	get/listen
can_jump_to_next_cue	bool	get/listen
can_jump_to_prev_cue	bool	get/listen
can_redo	bool	get
can_undo	bool	get
canonical_parent	None	get
clip_trigger_quantization	Quantization	get/set/listen
count_in_duration	int	get/listen
cue_points	Vector[CuePoint]	get/listen
current_song_time	float	get/set/listen
exclusive_arm	bool	get/listen
exclusive_solo	bool	get
file_path	str	get
groove_amount	float	get/set/listen
groove_pool	GroovePool	get
is_ableton_link_enabled	bool	get/set/listen
is_ableton_link_start_stop_sync_enabled	bool	get/set/listen
is_counting_in	bool	get/listen
is_playing	bool	get/set/listen
last_event_time	float	get
loop	bool	get/set/listen
loop_length	float	get/set/listen
loop_start	float	get/set/listen
master_track	Track	get
metronome	bool	get/set/listen
midi_recording_quantization	RecordingQuantization	get/set/listen
name	str	get
nudge_down	bool	get/set/listen
nudge_up	bool	get/set/listen
overdub	bool	get/set/listen
punch_in	bool	get/set/listen
punch_out	bool	get/set/listen
re_enable_automation_enabled	bool	get/listen
record_mode	bool	get/set/listen
return_tracks	Vector[Track]	get/listen
root_note	int	get/set/listen
scale_intervals	IntVector	get/listen
scale_mode	bool	get/set/listen
scale_name	str	get/set/listen
scenes	Vector[Scene]	get/listen
select_on_launch	bool	get
session_automation_record	bool	get/set/listen
session_record	bool	get/set/listen
session_record_status	int	get/listen
signature_denominator	int	get/set/listen
signature_numerator	int	get/set/listen
song_length	float	get/listen
start_time	float	get/set/listen
swing_amount	float	get/set/listen
tempo	float	get/set/listen
tempo_follower_enabled	bool	get/set/listen
tracks	Vector[Track]	get/listen
tuning_system	TuningSystem	get/listen
view	View	get
visible_tracks	Vector[Track]	get/listen

appointed_device

• Type: Device | None
• Settable: yes
• Listenable: yes

Read, write, and listen access to the appointed Device

arrangement_overdub

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set the global arrangement overdub state.

back_to_arranger

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set if triggering a Clip in the Session, disabled the playback of Clips in the Arranger.

can_capture_midi

• Type: bool
• Settable: no
• Listenable: yes

Get whether there currently is material to be captured on any tracks.

can_jump_to_next_cue

• Type: bool
• Settable: no
• Listenable: yes

Returns true when there is a cue marker right to the playing pos that we could jump to.

can_jump_to_prev_cue

• Type: bool
• Settable: no
• Listenable: yes

Returns true when there is a cue marker left to the playing pos that we could jump to.

can_redo

• Type: bool
• Settable: no
• Listenable: no

Returns true if there is an undone action that we can redo.

can_undo

• Type: bool
• Settable: no
• Listenable: no

Returns true if there is an action that we can restore.

canonical_parent

• Type: None
• Settable: no
• Listenable: no

Get the canonical parent of the song.

clip_trigger_quantization

• Type: Quantization
• Settable: yes
• Listenable: yes

Get/Set access to the quantization settings that are used to fire Clips in the Session.

count_in_duration

• Type: int
• Settable: no
• Listenable: yes

Get the count in duration. Returns an index, mapped as follows: 0 - None, 1 - 1 Bar, 2 - 2 Bars, 3 - 4 Bars.

cue_points

• Type: Vector[CuePoint]
• Settable: no
• Listenable: yes

Const access to a list of all cue points of the Live Song.

current_song_time

• Type: float
• Settable: yes
• Listenable: yes

Get/Set access to the songs current playing position in beats.

exclusive_arm

• Type: bool
• Settable: no
• Listenable: yes

Get if Tracks should be armed exclusively by default.

exclusive_solo

• Type: bool
• Settable: no
• Listenable: no

Get if Tracks should be soloed exclusively by default.

file_path

• Type: str
• Settable: no
• Listenable: no

Get the current Live Set's path on disk.

groove_amount

• Type: float
• Settable: yes
• Listenable: yes

Get/Set the global groove amount, that adjust all setup grooves in all clips.

groove_pool

• Type: GroovePool
• Settable: no
• Listenable: no

Get the groove pool.

is_ableton_link_enabled

• Type: bool
• Settable: yes
• Listenable: yes

Enable/disable Ableton Link.

is_ableton_link_start_stop_sync_enabled

• Type: bool
• Settable: yes
• Listenable: yes

Enable/disable Ableton Link Start Stop Sync.

is_counting_in

• Type: bool
• Settable: no
• Listenable: yes

Get whether currently counting in.

is_playing

• Type: bool
• Settable: yes
• Listenable: yes

Returns true if the Song is currently playing.

last_event_time

• Type: float
• Settable: no
• Listenable: no

Return the time of the last set event in the song. In contrary to song_length, this will not add some extra beats that are mostly needed for Display purposes in the Arrangerview.

loop

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set the looping flag that en/disables the usage of the global loop markers in the song.

loop_length

• Type: float
• Settable: yes
• Listenable: yes

Get/Set the length of the global loop marker position in beats.

loop_start

• Type: float
• Settable: yes
• Listenable: yes

Get/Set the start of the global loop marker position in beats.

master_track

• Type: Track
• Settable: no
• Listenable: no

Access to the Main Track (always available)

metronome

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set if the metronom is audible.

midi_recording_quantization

• Type: RecordingQuantization
• Settable: yes
• Listenable: yes

Get/Set access to the settings that are used to quantize MIDI recordings.

name

• Type: str
• Settable: no
• Listenable: no

Get the current Live Set's name.

nudge_down

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set the status of the nudge down button.

nudge_up

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set the status of the nudge up button.

overdub

• Type: bool
• Settable: yes
• Listenable: yes

Legacy hook for Live 8 overdub state. Now hooks to session record, but never starts playback.

punch_in

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set the flag that will enable recording as soon as the Song plays and hits the global loop start region.

punch_out

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set the flag that will disable recording as soon as the Song plays and hits the global loop end region.

re_enable_automation_enabled

• Type: bool
• Settable: no
• Listenable: yes

Returns true if some automated parameter has been overriden

record_mode

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set the state of the global recording flag.

return_tracks

• Type: Vector[Track]
• Settable: no
• Listenable: yes

Const access to the list of available Return Tracks.

root_note

• Type: int
• Settable: yes
• Listenable: yes

Set and access the root (i.e. key) of the song. The root can be a number between 0 and 11, with 0 corresponding to C and 11 corresponding to B.

scale_intervals

• Type: IntVector
• Settable: no
• Listenable: yes

Reports the current scale's intervals as a list of integers, starting with the root and representing the number of halfsteps (e.g. Major -> 0, 2, 4, 5, 7, 9, 11)

scale_mode

• Type: bool
• Settable: yes
• Listenable: yes

Access to the Scale Mode setting in Live. When on, key tracks that belong to the currently selected scale are highlighted in Live's MIDI Note Editor, and pitch-based parameters in MIDI Tools and Devices can be edited in scale degrees rather than semitones.

scale_name

• Type: str
• Settable: yes
• Listenable: yes

Set and access the currently selected scale by name. The default scale names that can be saved with a set and recalled are 'Major', 'Minor', 'Dorian', 'Mixolydian' ,'Lydian' ,'Phrygian' ,'Locrian', 'Whole Tone', 'Half-whole Dim.', 'Whole-half Dim.', 'Minor Blues', 'Minor Pentatonic', 'Major Pentatonic', 'Harmonic Minor', 'Harmonic Major', 'Dorian #4', 'Phrygian Dominant', 'Melodic Minor', 'Lydian Augmented', 'Lydian Dominant', 'Super Locrian', 'Bhairav', 'Hungarian Minor', '8-Tone Spanish', 'Hirajoshi', 'In-Sen', 'Iwato', 'Kumoi', 'Pelog Selisir', 'Pelog Tembung', 'Messiaen 3', 'Messiaen 4', 'Messiaen 5', 'Messiaen 6', 'Messiaen 7'

scenes

• Type: Vector[Scene]
• Settable: no
• Listenable: yes

Const access to a list of all Scenes in the Live Song.

select_on_launch

• Type: bool
• Settable: no
• Listenable: no

Get if Scenes and Clips should be selected when fired.

session_automation_record

• Type: bool
• Settable: yes
• Listenable: yes

Returns true if automation recording is enabled.

session_record

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set the session record state.

session_record_status

• Type: int
• Settable: no
• Listenable: yes

Get the session slot-recording state.

signature_denominator

• Type: int
• Settable: yes
• Listenable: yes

Get/Set access to the global signature denominator of the Song.

signature_numerator

• Type: int
• Settable: yes
• Listenable: yes

Get/Set access to the global signature numerator of the Song.

song_length

• Type: float
• Settable: no
• Listenable: yes

Return the time of the last set event in the song, plus som extra beats that are usually added for better navigation in the arrangerview.

start_time

• Type: float
• Settable: yes
• Listenable: yes

Get/Set access to the songs current start time in beats. The set time may be overridden by the current loop/locator start time.

swing_amount

• Type: float
• Settable: yes
• Listenable: yes

Get/Set access to the amount of swing that is applied when adding or quantizing notes to MIDI clips

tempo

• Type: float
• Settable: yes
• Listenable: yes

Get/Set the global project tempo.

tempo_follower_enabled

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set whether the Tempo Follower is controlling the tempo. The Tempo Follower Toggle must be made visible in the preferences for this property to be effective.

tracks

• Type: Vector[Track]
• Settable: no
• Listenable: yes

Const access to a list of all Player Tracks in the Live Song, excluding the return and Main Track (see also Song.send_tracks and Song.master_track). At least one MIDI or Audio Track is always available.

tuning_system

• Type: TuningSystem
• Settable: no
• Listenable: yes

Access the currently active tuning system.

view

• Type: View
• Settable: no
• Listenable: no

Representing the view aspects of a Live document: The Session and Arrangerview.

visible_tracks

• Type: Vector[Track]
• Settable: no
• Listenable: yes

Const access to a list of all visible Player Tracks in the Live Song, excluding the return and Main Track (see also Song.send_tracks and Song.master_track). At least one MIDI or Audio Track is always available.

Methods

Method	Returns
begin_undo_step()	None
capture_and_insert_scene()	None
capture_midi()	None
continue_playing()	None
create_audio_track()	Track
create_midi_track()	Track
create_return_track()	Track
create_scene()	Scene
delete_return_track()	None
delete_scene()	None
delete_track()	None
duplicate_scene()	None
duplicate_track()	None
end_undo_step()	None
find_device_position()	int
force_link_beat_time()	None
get_beats_loop_length()	BeatTime
get_beats_loop_start()	BeatTime
get_current_beats_song_time()	BeatTime
get_current_smpte_song_time()	SmptTime
get_data()	Any
is_cue_point_selected()	bool
jump_by()	None
jump_to_next_cue()	None
jump_to_prev_cue()	None
move_device()	int
play_selection()	None
re_enable_automation()	None
redo()	str
scrub_by()	None
set_data()	None
set_or_delete_cue()	None
start_playing()	None
stop_all_clips()	None
stop_playing()	None
tap_tempo()	None
trigger_session_record()	None
undo()	str

begin_undo_step()

• Returns: None

capture_and_insert_scene(capture_mode: CaptureMode | int = 0)

• Returns: None
• Args:
• capture_mode: CaptureMode | int = 0

Capture currently playing clips and insert them as a new scene after the selected scene. Raises a runtime error if creating a new scene would exceed the limitations.

capture_midi(destination: CaptureDestination | int = 0)

• Returns: None
• Args:
• destination: CaptureDestination | int = 0

Capture recently played MIDI material from audible tracks. If no Destination is given or Destination is set to CaptureDestination.auto, the captured material is inserted into the Session or Arrangement depending on which is visible. If Destination is set to CaptureDestination.session or CaptureDestination.arrangement, inserts the material into Session or Arrangement, respectively. Raises a limitation error when capturing into the Session and a new scene would have to be created but can't because it would exceed the limitations.

continue_playing()

• Returns: None

Continue playing the song from the current position

create_audio_track(index: int = None)

• Returns: Track
• Args:
• index: int = None

Create a new audio track at the optional given index and return it.If the index is -1, the new track is added at the end. It will create a default audio track if possible. If the index is invalid or the new track would exceed the limitations, a limitation error is raised.If the index is missing, the track is created after the last selected item

create_midi_track(index: int = None)

• Returns: Track
• Args:
• index: int = None

Create a new midi track at the optional given index and return it.If the index is -1, the new track is added at the end.It will create a default midi track if possible. If the index is invalid or the new track would exceed the limitations, a limitation error is raised.If the index is missing, the track is created after the last selected item

create_return_track()

• Returns: Track

Create a new return track at the end and return it. If the new track would exceed the limitations, a limitation error is raised. If the maximum number of return tracks is exceeded, a RuntimeError is raised.

create_scene(index: int)

• Returns: Scene
• Args:
• index: int

Create a new scene at the given index. If the index is -1, the new scene is added at the end. If the index is invalid or the new scene would exceed the limitations, a limitation error is raised.

delete_return_track(index: int)

• Returns: None
• Args:
• index: int

Delete the return track with the given index. If no track with this index exists, an exception will be raised.

delete_scene(index: int)

• Returns: None
• Args:
• index: int

Delete the scene with the given index. If no scene with this index exists, an exception will be raised.

delete_track(index: int)

• Returns: None
• Args:
• index: int

Delete the track with the given index. If no track with this index exists, an exception will be raised.

duplicate_scene(index: int)

• Returns: None
• Args:
• index: int

Duplicates a scene and selects the new one. Raises a limitation error if creating a new scene would exceed the limitations.

duplicate_track(index: int)

• Returns: None
• Args:
• index: int

Duplicates a track and selects the new one. If the track is inside a folded group track, the group track is unfolded. Raises a limitation error if creating a new track would exceed the limitations.

end_undo_step()

• Returns: None

find_device_position(device: Device, target: Track | Chain, target_position: int)

• Returns: int
• Args:
• device: Device
• target: Track | Chain
• target_position: int

Returns the closest possible position to the given target, where the device can be inserted. If inserting is not possible at all (i.e. if the device type is wrong), -1 is returned.

force_link_beat_time()

• Returns: None

Force the Link timeline to jump to Lives current beat time. Danger: This can cause beat time discontinuities in other connected apps.

get_beats_loop_length()

• Returns: BeatTime

Get const access to the songs loop length, using a BeatTime class with the current global set signature.

get_beats_loop_start()

• Returns: BeatTime

Get const access to the songs loop start, using a BeatTime class with the current global set signature.

get_current_beats_song_time()

• Returns: BeatTime

Get const access to the songs current playing position, using a BeatTime class with the current global set signature.

get_current_smpte_song_time(smpte_format: int)

• Returns: SmptTime
• Args:
• smpte_format: int

Get const access to the songs current playing position, by specifying the SMPTE format in which you would like to receive the time.

get_data(key: str, default_value: Any)

• Returns: Any
• Args:
• key: str
• default_value: Any

Get data for the given key, that was previously stored using set_data.

is_cue_point_selected()

• Returns: bool

Return true if the global playing pos is currently on a cue point.

jump_by(beats: float)

• Returns: None
• Args:
• beats: float

Set a new playing pos, relative to the current one.

jump_to_next_cue()

• Returns: None

Jump to the next cue (marker) if possible.

jump_to_prev_cue()

• Returns: None

Jump to the prior cue (marker) if possible.

move_device(device: Device, target: Track | Chain, target_position: int)

• Returns: int
• Args:
• device: Device
• target: Track | Chain
• target_position: int

Move a device into the target at the given position, where 0 moves it before the first device and len(devices) moves it to the end of the device chain.If the device cannot be moved to this position, the nearest possible position is chosen. If the device type is not valid, a runtime error is raised.Returns the index, where the device was moved to.

play_selection()

• Returns: None

Start playing the current set selection, or do nothing if no selection is set.

re_enable_automation()

• Returns: None

Discards overrides of automated parameters.

redo()

• Returns: str

Redo the last action that was undone.

scrub_by(beats: float)

• Returns: None
• Args:
• beats: float

Same as jump_by, but does not stop playback.

set_data(key: str, value: Any)

• Returns: None
• Args:
• key: str
• value: Any

Store data for the given key in this object. The data is persistent and will be restored when loading the Live Set.

set_or_delete_cue()

• Returns: None

When a cue is selected, it gets deleted. If no cue is selected, a new cue is created at the current global songtime.

start_playing()

• Returns: None

Start playing from the startmarker

stop_all_clips(quantized: bool = True)

• Returns: None
• Args:
• quantized: bool = True

Stop all playing Clips (if any) but continue playing the Song.

stop_playing()

• Returns: None

Stop playing the Song.

tap_tempo()

• Returns: None

Trigger the tap tempo function.

trigger_session_record(record_length: float = 1.7976931348623157e+308)

• Returns: None
• Args:
• record_length: float = 1.7976931348623157e+308

Triggers a new session recording.

undo()

• Returns: str

Undo the last action that was made.

Song.View (Subclass)

Live.Song.Song.View

Representing the view aspects of a Live document: The Session and Arrangerview.

Live Object: yes

Properties

Property	Type	Supports
canonical_parent	Song	get
detail_clip	Clip \| None	get/set/listen
draw_mode	bool	get/set/listen
follow_song	bool	get/set/listen
highlighted_clip_slot	ClipSlot	get/set
selected_chain	Chain \| None	get/set/listen
selected_parameter	DeviceParameter \| None	get/listen
selected_scene	Scene	get/set/listen
selected_track	Track	get/set/listen

canonical_parent

• Type: Song
• Settable: no
• Listenable: no

Get the canonical parent of the song view.

detail_clip

• Type: Clip | None
• Settable: yes
• Listenable: yes

Get/Set the Clip that is currently visible in Lives Detailview.

draw_mode

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set if the Envelope/Note draw mode is enabled.

follow_song

• Type: bool
• Settable: yes
• Listenable: yes

Get/Set if the Arrangerview should scroll to show the playmarker.

highlighted_clip_slot

• Type: ClipSlot
• Settable: yes
• Listenable: no

Get/Set the clip slot, defined via the selected track and scene in the Session.Will be None for Main- and Sendtracks.

selected_chain

• Type: Chain | None
• Settable: yes
• Listenable: yes

Get the highlighted chain if available.

selected_parameter

• Type: DeviceParameter | None
• Settable: no
• Listenable: yes

Get the currently selected device parameter.

selected_scene

• Type: Scene
• Settable: yes
• Listenable: yes

Get/Set the current selected scene in Lives Sessionview.

selected_track

• Type: Track
• Settable: yes
• Listenable: yes

Get/Set the current selected Track in Lives Session or Arrangerview.

Methods

Method	Returns
select_device()	None

select_device(device: Device, should_appoint_device: bool = True)

• Returns: None
• Args:
• device: Device
• should_appoint_device: bool = True

Select the given device.

Enums

CaptureDestination

Live.Song.CaptureDestination

The destination for MIDI capture.

Value	Name
0	auto
1	session
2	arrangement

CaptureMode

Live.Song.CaptureMode

The capture mode that is used for capture and insert scene.

Value	Name
0	all
1	all_except_selected

Quantization

Live.Song.Quantization

Value	Name
0	q_no_q
1	q_8_bars
2	q_4_bars
3	q_2_bars
4	q_bar
5	q_half
6	q_half_triplet
7	q_quarter
8	q_quarter_triplet
9	q_eight
10	q_eight_triplet
11	q_sixtenth
12	q_sixtenth_triplet
13	q_thirtytwoth

RecordingQuantization

Live.Song.RecordingQuantization

Value	Name
0	rec_q_no_q
1	rec_q_quarter
2	rec_q_eight
3	rec_q_eight_triplet
4	rec_q_eight_eight_triplet
5	rec_q_sixtenth
6	rec_q_sixtenth_triplet
7	rec_q_sixtenth_sixtenth_triplet
8	rec_q_thirtysecond

SessionRecordStatus

Live.Song.SessionRecordStatus

Value	Name
0	off
1	on
2	transition

TimeFormat

Live.Song.TimeFormat

Value	Name
0	ms_time
1	smpte_24
2	smpte_25
3	smpte_30
4	smpte_30_drop
5	smpte_29

BeatTime (Type)

Live.Song.BeatTime

Represents a Time, splitted into Bars, Beats, SubDivision and Ticks.

Constructor: BeatTime()

Properties

Property	Type	Supports
bars	int	get/set
beats	int	get/set
sub_division	int	get/set
ticks	int	get/set

bars

• Type: int
• Settable: yes
• Listenable: no

beats

• Type: int
• Settable: yes
• Listenable: no

sub_division

• Type: int
• Settable: yes
• Listenable: no

ticks

• Type: int
• Settable: yes
• Listenable: no

CuePoint (Type)

Live.Song.CuePoint

Represents a 'Marker' in the arrangement.

Live Object: yes

Properties

Property	Type	Supports
canonical_parent	Song	get
name	str	get/set/listen
time	float	get/listen

canonical_parent

• Type: Song
• Settable: no
• Listenable: no

Get the canonical parent of the cue point.

name

• Type: str
• Settable: yes
• Listenable: yes

Get/Set/Listen to the name of this CuePoint, as visible in the arranger.

time

• Type: float
• Settable: no
• Listenable: yes

Get/Listen to the CuePoint's time in beats.

Methods

Method	Returns
jump()	None

jump()

• Returns: None

When the Song is playing, set the playing-position quantized to this Cuepoint's time. When not playing, simply move the start playing position.

SmptTime (Type)

Live.Song.SmptTime

Represents a Time, split into Hours, Minutes, Seconds and Frames. The frame type must be specified when calling a function that returns a SmptTime.

Constructor: SmptTime()

Properties

Property	Type	Supports
frames	int	get/set
hours	int	get/set
minutes	int	get/set
seconds	int	get/set

frames

• Type: int
• Settable: yes
• Listenable: no

hours

• Type: int
• Settable: yes
• Listenable: no

minutes

• Type: int
• Settable: yes
• Listenable: no

seconds

• Type: int
• Settable: yes
• Listenable: no

Module Functions

Function	Returns
get_all_scales_ordered()	tuple[tuple[str, tuple[int, Ellipsis]], Ellipsis]

get_all_scales_ordered()

• Returns: tuple[tuple[str, tuple[int, Ellipsis]], Ellipsis]

Get an ordered tuple of tuples of all available scale names to intervals.