ableton-osc/README.md

AbletonOSC

A full-coverage Ableton Live 11 remote script that exposes the entire Live Object Model over UDP/OSC. Drop it into Live's MIDI Remote Scripts directory, select it in preferences, and control every aspect of your session from any language or tool that speaks OSC.

Zero external runtime dependencies — OSC encoding and decoding are implemented from scratch in pure Python, so nothing needs to be installed inside Ableton's embedded Python environment.

---

Table of contents

• Installation
• Network configuration
• Protocol reference
  • Address schema
  • Operations
  • Type mapping
  • Indexing
  • Wildcard support
  • Response format
  • Listener pattern
• Control endpoints
• Song
• Track
• Return track
• Clip slot
• Clip
• Device
• Scene
• View
• Application
• Browser
• Groove
• Development setup
• Architecture

---

Installation

1. Copy the AbletonOSC/ folder into Ableton Live's MIDI Remote Scripts directory:

   Platform	Path
   Windows	C:\ProgramData\Ableton\Live <version>\Resources\MIDI Remote Scripts\
   macOS	~/Library/Application Support/Ableton/Live <version>/Resources/MIDI Remote Scripts/

2. Start (or restart) Ableton Live.

3. Open Preferences → MIDI → Control Surfaces, set one of the slots to AbletonOSC.

4. Send a test ping:

   /live/test  →  reply: "AbletonOSC active"
   

---

Network configuration

Direction	Address	Port
Incoming (commands)	0.0.0.0 (all interfaces)	11000
Outgoing (replies / listener push)	sender's IP	11001

Ports can be overridden with environment variables before Live starts:

ABLETON_OSC_LISTEN_PORT=11000
ABLETON_OSC_SEND_PORT=11001

Replies are always sent to the IP of the most recent sender on port 11001. Running multiple clients simultaneously from the same IP works; running them from different IPs does not (last sender wins).

---

Protocol reference

Address schema

/live/<object>/<operation>/<property>   [index…]  [value…]
/live/<object>/<method>                 [index…]  [arg…]

Operations

Operation	Direction	Description
get	request → reply	Read the current value. The reply is sent back to the same address.
set	request only	Write a value. No reply is sent unless documented otherwise.
start_listen	request	Attach a Live listener; sends the current value immediately, then pushes updates to the get address whenever the value changes.
stop_listen	request	Detach the previously registered listener.

Methods (e.g. /live/song/start_playing) have no operation verb. They are fire-and-forget unless explicitly noted as returning a value.

Type mapping

OSC types used in this implementation:

OSC tag	Python type	Notes
i	int	32-bit signed integer
f	float	32-bit IEEE 754
s	str	UTF-8, null-padded to 4-byte boundary
T / F	bool	OSC true/false atoms
N	None	OSC nil

Booleans in replies are sent as OSC T/F. Booleans in incoming messages are accepted as T/F, 1/0 int, or True/False float.

Indexing

• All indices are zero-based.
• track_index refers to the position in song.tracks (not including return tracks).
• clip_index / slot_index refers to the clip slot position within the track (row in the session view, 0 = top).
• device_index refers to the position in track.devices.
• param_index refers to the position in device.parameters.
• scene_index refers to the position in song.scenes.

Wildcard support

Track handlers accept * in place of track_index. The handler iterates all tracks and returns one response per track, prefixed with that track's index.

/live/track/get/volume *
→  0  0.85  1  0.72  2  1.0  ...

Response format

A reply is sent to the same OSC address as the request, with the value appended. For indexed objects (track, clip, device, scene), the index(es) are included in the reply so responses from wildcard queries or multiple listeners can be correlated:

Request:   /live/track/get/mute   2
Reply:     /live/track/get/mute   2  0       (track 2, mute=false)

Request:   /live/clip/get/name    0  3
Reply:     /live/clip/get/name    0  3  "My Clip"

Request:   /live/device/get/parameter/value   1  0  5
Reply:     /live/device/get/parameter/value   1  0  5  0.75

When a handler returns multiple values (e.g. a list of names), they are flattened into OSC arguments:

/live/song/get/track_names   →   "Drums"  "Bass"  "Lead"  ...
/live/track/get/clips/name 0 →   "Loop A"  "Loop B"  ...

Listener pattern

# Subscribe — receives current value immediately, then on every change:
/live/song/start_listen/tempo
→ /live/song/get/tempo  120.0

# … every time tempo changes Live pushes:
→ /live/song/get/tempo  124.0

# Unsubscribe:
/live/song/stop_listen/tempo

Listeners survive a /live/api/reload only if you re-send start_listen after the reload.

---

Control endpoints

Address	Args	Description
/live/test	—	Connectivity check. Replies "AbletonOSC active".
/live/startup	—	Sent automatically by the script on load.
/live/shutdown	—	Sent automatically by the script on disconnect.
/live/error	string	Sent by the script when a handler throws an unhandled exception.
/live/api/reload	—	Clears and re-registers all handlers. Replies "reloaded".
/live/api/show_message	string	Displays a string in Live's status bar.

---

Song

The song object is a singleton; no index is needed.

Properties

Read / write

Property	Type	Description
tempo	float	BPM (60–200)
time_signature_numerator	int	Beats per bar
time_signature_denominator	int	Beat unit (2, 4, 8, 16…)
loop	bool	Arrangement loop on/off
loop_start	float	Loop start in beats
loop_length	float	Loop length in beats
current_song_time	float	Playback position in beats
metronome	bool	Metronome on/off
record_mode	bool	Arrangement record on/off
arrangement_overdub	bool	Arrangement overdub on/off
session_record	bool	Session record armed
overdub	bool	Clip overdub on/off
groove_amount	float	Global groove intensity (0–1)
swing_amount	float	Global swing amount (0–1)
clip_trigger_quantization	int	Clip launch quantization enum
midi_recording_quantization	int	MIDI recording quantization enum
punch_in	bool	Arrangement punch-in enabled
punch_out	bool	Arrangement punch-out enabled
exclusive_arm	bool	Solo arm mode on/off
exclusive_solo	bool	Exclusive solo mode on/off

Read-only

Property	Type	Description
is_playing	bool	True while transport is running
can_undo	bool	Undo history available
can_redo	bool	Redo history available
song_length	float	Total arrangement length in beats
session_record_status	int	Session record state enum

Aggregate queries

Address	Args	Reply	Description
/live/song/get/num_tracks	—	int	Number of tracks
/live/song/get/num_scenes	—	int	Number of scenes
/live/song/get/num_return_tracks	—	int	Number of return tracks
/live/song/get/track_names	[start] [end]	string…	Track names, optionally sliced
/live/song/get/scene_names	[start] [end]	string…	Scene names, optionally sliced
/live/song/get/return_track_names	—	string…	Return track names
/live/song/get/cue_points	—	string float …	Interleaved name/time pairs

Methods

Address	Args	Reply	Description
/live/song/start_playing	—	—	Start transport from current position
/live/song/stop_playing	—	—	Stop transport
/live/song/continue_playing	—	—	Resume from current position
/live/song/stop_all_clips	—	—	Stop all playing clips
/live/song/undo	—	—	Undo last action
/live/song/redo	—	—	Redo last undone action
/live/song/tap_tempo	—	—	Tap tempo
/live/song/trigger_session_record	—	—	Toggle session record
/live/song/re_enable_automation	—	—	Re-enable all disabled automation
/live/song/capture_midi	—	—	Capture MIDI from input
/live/song/jump_by	float	—	Jump playback position by N beats
/live/song/jump_to_next_cue	—	—	Jump to next cue point
/live/song/jump_to_prev_cue	—	—	Jump to previous cue point
/live/song/create_audio_track	[index]	int	Create audio track at index (−1 = end), returns new track count
/live/song/create_midi_track	[index]	int	Create MIDI track at index
/live/song/create_return_track	—	—	Append a return track
/live/song/create_scene	[index]	int	Create scene at index, returns new scene count
/live/song/delete_track	track_index	—	Delete a track
/live/song/delete_scene	scene_index	—	Delete a scene
/live/song/delete_return_track	return_index	—	Delete a return track
/live/song/duplicate_track	track_index	—	Duplicate a track
/live/song/duplicate_scene	scene_index	—	Duplicate a scene

Beat listener (special)

The beat listener fires on every beat change during playback, not just when a property is set.

/live/song/start_listen/beat   →   pushes /live/song/get/beat  <beat_number:int>
/live/song/stop_listen/beat

---

Track

Addresses all regular session/audio/MIDI/group tracks. Return tracks use /live/return_track/ (same API surface).

Properties

All track property requests take track_index as the first argument. Use * to query all tracks at once.

Read / write

Property	Type	Description
arm	bool	Record arm
mute	bool	Mute
solo	bool	Solo
name	string	Track name
color	int	Track color as packed RGB integer
color_index	int	Track color index
fold_state	bool	Group track folded
current_monitoring_state	int	0=In, 1=Auto, 2=Off

Read-only

Property	Type	Description
can_be_armed	bool	Whether the track supports arming
has_audio_input	bool	—
has_audio_output	bool	—
has_midi_input	bool	—
has_midi_output	bool	—
is_foldable	bool	Group track
is_grouped	bool	Track is inside a group
is_visible	bool	Track visible in session
fired_slot_index	int	Index of slot queued to play (−1 if none)
playing_slot_index	int	Index of currently playing slot (−1 if none)
output_meter_level	float	Combined output level (0–1)
output_meter_left	float	Left channel level
output_meter_right	float	Right channel level
output_meter_peak_left	float	Left peak
output_meter_peak_right	float	Right peak

Mixer device

Address	Args	Reply	Description
/live/track/get/volume	track_index	track_index float	Fader level (0–1 linear; 0.85 ≈ 0 dB)
/live/track/set/volume	track_index float	—	Set fader level
/live/track/start_listen/volume	track_index	—	Push volume changes
/live/track/stop_listen/volume	track_index	—
/live/track/get/panning	track_index	track_index float	Pan (−1 left … 0 centre … 1 right)
/live/track/set/panning	track_index float	—
/live/track/start_listen/panning	track_index	—	Push panning changes
/live/track/stop_listen/panning	track_index	—
/live/track/get/send	track_index send_index	track_index send_index float	Send level (0–1)
/live/track/set/send	track_index send_index float	—	Set send level
/live/track/start_listen/send	track_index send_index	—	Push send level changes
/live/track/stop_listen/send	track_index send_index	—

Routing

Address	Args	Reply	Description
/live/track/get/available_input_routing_types	track_index	string…	Available input type names
/live/track/get/available_input_routing_channels	track_index	string…	Available input channel names
/live/track/get/input_routing_type	track_index	string	Current input type name
/live/track/set/input_routing_type	track_index string	—	Set input type by display name
/live/track/get/input_routing_channel	track_index	string	Current input channel name
/live/track/set/input_routing_channel	track_index string	—	Set input channel by display name
/live/track/get/available_output_routing_types	track_index	string…	Available output type names
/live/track/get/available_output_routing_channels	track_index	string…	Available output channel names
/live/track/get/output_routing_type	track_index	string	Current output type name
/live/track/set/output_routing_type	track_index string	—	Set output type by display name
/live/track/get/output_routing_channel	track_index	string	Current output channel name
/live/track/set/output_routing_channel	track_index string	—	Set output channel by display name

Aggregate clip info

Address	Args	Reply	Description
/live/track/get/clips/name	track_index	string…	Names of all occupied session slots
/live/track/get/clips/length	track_index	float…	Lengths in beats
/live/track/get/clips/color	track_index	int…	Colors
/live/track/get/clips/is_playing	track_index	bool…	Playing states
/live/track/get/arrangement_clips/name	track_index	string…	Arrangement clip names
/live/track/get/arrangement_clips/length	track_index	float…	Arrangement clip lengths
/live/track/get/arrangement_clips/start_time	track_index	float…	Arrangement clip start times in beats

Device info

Address	Args	Reply	Description
/live/track/get/num_devices	track_index	int	Number of devices on track
/live/track/get/devices/name	track_index	string…	Device names
/live/track/get/devices/type	track_index	int…	Device types (0=audio_effect, 1=instrument, 2=midi_effect)
/live/track/get/devices/class_name	track_index	string…	Device class names (e.g. "Reverb", "Operator")
/live/track/get/devices/can_have_chains	track_index	bool…	Whether each device is a rack

Methods

Address	Args	Description
/live/track/stop_all_clips	track_index (or *)	Stop all clips on track(s)
/live/track/delete_device	track_index device_index	Delete a device
/live/track/duplicate_device	track_index device_index	Duplicate a device

---

Return track

Identical API surface to /live/track/, accessed via /live/return_track/.

Supported properties: name, mute, solo, color, color_index, output_meter_level, output_meter_left, output_meter_right, plus volume, panning, send, num_devices, devices/name.

---

Clip slot

Addresses a single cell in the session grid. Indexed by (track_index, slot_index).

Properties

Property	R/W	Type	Description
has_clip	R	bool	Whether a clip occupies the slot
is_playing	R	bool	Clip currently playing
is_triggered	R	bool	Clip queued to play
is_recording	R	bool	Clip currently recording
is_group_slot	R	bool	Slot belongs to a group track
controls_other_clips	R	bool	Group slot that controls children
playing_status	R	int	Playback status enum
will_record_on_start	R	bool	Will record when triggered
has_stop_button	R/W	bool	Slot has a stop button visible

Methods

Address	Args	Description
/live/clip_slot/fire	track_index slot_index	Launch the clip (or empty slot)
/live/clip_slot/stop	track_index slot_index	Stop playback
/live/clip_slot/create_clip	track_index slot_index [length]	Create a new empty MIDI clip; length in beats (default 4)
/live/clip_slot/delete_clip	track_index slot_index	Delete the clip in this slot
/live/clip_slot/duplicate_clip_to	src_track src_slot dst_track dst_slot	Copy clip to another slot

---

Clip

Addresses the clip object inside a slot. Indexed by (track_index, clip_index). All replies include the two indices as a prefix.

Properties

Read / write

Property	Type	Description
name	string	Clip name
color	int	Color (packed RGB)
color_index	int	Color index
muted	bool	Clip muted
gain	float	Clip gain (0–1)
pitch_coarse	int	Transpose in semitones (−48…+48)
pitch_fine	float	Detune in cents (−50…+50)
velocity_amount	float	Velocity deviation
looping	bool	Loop enabled
loop_start	float	Loop start in beats
loop_end	float	Loop end in beats
start_marker	float	Start marker in beats
end_marker	float	End marker in beats
warping	bool	Warp enabled (audio clips)
warp_mode	int	Warp mode enum (0=Beats, 1=Tones, …)
launch_mode	int	0=Trigger, 1=Gate, 2=Toggle, 3=Repeat
launch_quantization	int	Clip launch quantization enum
ram_mode	bool	RAM mode (audio clips)

Read-only

Property	Type	Description
is_playing	bool	Currently playing
is_recording	bool	Currently recording
is_midi_clip	bool	—
is_audio_clip	bool	—
is_overdubbing	bool	—
is_triggered	bool	Queued to play
will_record_on_start	bool	—
has_groove	bool	Groove assigned
length	float	Clip length in beats
start_time	float	Start position in arrangement (beats)
end_time	float	End position in arrangement (beats)
playing_position	float	Current playback position in clip (beats)
sample_length	float	Sample length in seconds (audio clips)
gain_display_string	string	Human-readable gain string
file_path	string	Audio file path (audio clips)

Playback methods

Address	Args	Description
/live/clip/fire	track_index clip_index	Launch the clip
/live/clip/stop	track_index clip_index	Stop the clip
/live/clip/duplicate_loop	track_index clip_index	Double the loop length and duplicate content
/live/clip/quantize	track_index clip_index [quantization] [strength]	Quantize notes; quantization is a Live enum int (default 4 = 1/16), strength 0–1 (default 1.0)

MIDI notes

Notes in the classic API are represented as flat 5-tuples per note: pitch start_time duration velocity mute.

Times and durations are in beats (floats). Pitch and velocity are MIDI integers 0–127. Mute is 0 or 1.

Address	Args	Reply	Description
/live/clip/get/notes	track_index clip_index	track clip pitch start dur vel mute …	All notes in clip
/live/clip/get/notes	track_index clip_index pitch pitch_span time time_span	track clip pitch start dur vel mute …	Filtered by pitch range and time range
/live/clip/add/notes	track clip pitch start dur vel mute [pitch start dur vel mute …]	—	Add one or more notes (multiples of 5 args after indices)
/live/clip/remove/notes	track clip	—	Remove all notes
/live/clip/remove/notes	track clip time time_span pitch pitch_span	—	Remove notes in range

Extended note API (Live 11+)

Returns 8 values per note: pitch start_time duration velocity mute note_id release_velocity probability

Address	Args	Reply	Description
/live/clip/get/notes_extended	track clip	(8 values per note)	All notes with full properties including IDs
/live/clip/get/notes_extended	track clip pitch pitch_span time time_span	(8 values per note)	Filtered query
/live/clip/apply_note_modifications	track clip note_id pitch start dur vel mute rel_vel prob […]	—	Modify notes by ID; multiples of 8 args after indices

Automation envelopes

Envelopes are addressed by (track_index, clip_index, device_index, param_index).

Address	Args	Reply	Description
/live/clip/get/automation_envelope	track clip device param	track clip device param time val time val …	Sampled envelope points
/live/clip/create_automation_envelope	track clip device param	—	Create an envelope for the parameter
/live/clip/clear_envelope	track clip device param	—	Clear all events from one envelope
/live/clip/clear_all_envelopes	track clip	—	Clear all envelopes in the clip

Warp markers (audio clips)

Address	Args	Reply	Description
/live/clip/get/warp_markers	track clip	track clip beat_time sample_time …	Interleaved beat/sample time pairs

Groove

Address	Args	Reply	Description
/live/clip/get/groove	track clip	track clip groove_name	Name of assigned groove, or ""
/live/clip/set/groove	track clip groove_name	—	Assign groove by name; "" clears it

---

Device

Devices are addressed by (track_index, device_index). Parameters by (track_index, device_index, param_index).

Device properties

Address	Args	Reply	Description
/live/device/get/name	track device	track device string	Device name
/live/device/get/class_name	track device	track device string	Class name (e.g. "Reverb", "Eq8", "AuPluginDevice")
/live/device/get/type	track device	track device int	0=audio_effect, 1=instrument, 2=midi_effect
/live/device/get/is_active	track device	track device bool	On/off bypass state
/live/device/set/is_active	track device bool	—	Toggle bypass
/live/device/start_listen/is_active	track device	—	Push bypass changes
/live/device/stop_listen/is_active	track device	—

Bulk parameter operations

Most efficient way to read/write all parameters at once.

Address	Args	Reply	Description
/live/device/get/num_parameters	track device	track device int	Parameter count
/live/device/get/parameters/name	track device	track device string…	All parameter names
/live/device/get/parameters/value	track device	track device float…	All parameter values
/live/device/get/parameters/min	track device	track device float…	All parameter minimums
/live/device/get/parameters/max	track device	track device float…	All parameter maximums
/live/device/get/parameters/default_value	track device	track device float…	All parameter defaults
/live/device/get/parameters/is_quantized	track device	track device bool…	Whether each parameter is stepped/quantized
/live/device/set/parameters/value	track device val0 val1 …	—	Set all parameters; values mapped by position

Individual parameter operations

Address	Args	Reply	Description
/live/device/get/parameter/name	track device param	track device param string	Parameter name
/live/device/get/parameter/value	track device param	track device param float	Current value
/live/device/get/parameter/value_string	track device param	track device param string	Human-readable value (e.g. "2500 Hz")
/live/device/get/parameter/min	track device param	track device param float	Minimum value
/live/device/get/parameter/max	track device param	track device param float	Maximum value
/live/device/get/parameter/default_value	track device param	track device param float	Default value
/live/device/set/parameter/value	track device param float	—	Set parameter value
/live/device/start_listen/parameter/value	track device param	—	Push value changes; fires to /live/device/get/parameter/value
/live/device/stop_listen/parameter/value	track device param	—

Rack chains

For Instrument Racks, Effect Racks, and Drum Racks. chain_index is the chain position within the rack; sub_device_index is the device position within that chain.

Address	Args	Reply	Description
/live/device/get/num_chains	track device	track device int	Number of chains
/live/device/get/chains/name	track device	track device string…	Chain names
/live/device/get/chains/num_devices	track device	track device int…	Devices per chain
/live/device/get/chains/devices/name	track device	track device string…	Flattened names of all devices in all chains
/live/device/randomize_macros	track device	—	Randomize all macro knobs

Sub-device parameter access

Address	Args	Reply	Description
/live/device/chain/get/parameter/value	track device chain sub_device param	(all 5 indices + float)	Read a parameter inside a rack chain
/live/device/chain/set/parameter/value	track device chain sub_device param float	—	Set it
/live/device/chain/start_listen/parameter/value	track device chain sub_device param	—	Push value changes
/live/device/chain/stop_listen/parameter/value	track device chain sub_device param	—

Drum pads

Only meaningful on a Drum Rack device. pad_index is 0-based within the drum pad array.

Address	Args	Reply	Description
/live/device/get/drum_pads/name	track device	track device string…	Pad names
/live/device/get/drum_pads/note	track device	track device int…	MIDI note per pad
/live/device/get/drum_pads/mute	track device	track device bool…	Mute state per pad
/live/device/set/drum_pads/mute	track device pad_index bool	—	Mute/unmute a pad
/live/device/get/drum_pads/solo	track device	track device bool…	Solo state per pad
/live/device/set/drum_pads/solo	track device pad_index bool	—	Solo/unsolo a pad

---

Scene

Indexed by scene_index. All replies include the scene index as a prefix.

Properties

Read / write

Property	Type	Description
name	string	Scene name
color	int	Scene color (packed RGB)
color_index	int	Scene color index
tempo	float	Scene-specific BPM
tempo_enabled	bool	Whether the scene overrides tempo
time_signature_numerator	int	Scene-specific time signature numerator
time_signature_denominator	int	Scene-specific time signature denominator
time_signature_enabled	bool	Whether the scene overrides the time signature

Read-only

Property	Type	Description
is_empty	bool	No clips in any slot
is_triggered	bool	Scene is queued to launch

Methods and aggregate queries

Address	Args	Reply	Description
/live/scene/fire	scene_index	—	Launch the scene
/live/scene/fire_as_selected	scene_index	—	Launch and advance selection to next scene
/live/scene/get/num_clips	scene_index	scene_index int	Number of occupied slots in the scene
/live/scene/get/clip_slots/has_clip	scene_index	scene_index bool…	One bool per track slot

---

View

Controls the Live UI selection state. No index required.

Selected scene

Address	Args	Reply	Description
/live/view/get/selected_scene	—	int	Index of the selected scene
/live/view/set/selected_scene	scene_index	—	Select a scene
/live/view/start_listen/selected_scene	—	—	Push selection changes
/live/view/stop_listen/selected_scene	—	—

Selected track

Address	Args	Reply	Description
/live/view/get/selected_track	—	int	Index within tracks + return_tracks
/live/view/set/selected_track	track_index	—	Select a track
/live/view/start_listen/selected_track	—	—	Push selection changes
/live/view/stop_listen/selected_track	—	—

Selected clip / device

Address	Args	Reply	Description
/live/view/get/selected_clip	—	track_index clip_index	Currently displayed clip in Detail view
/live/view/set/selected_clip	track_index clip_index	—	Show a clip in the Detail view
/live/view/get/selected_device	—	track_index device_index	Selected device on current track

Focus

Address	Args	Description
/live/view/show_clip_detail_view	—	Switch Detail view to Clip
/live/view/show_device_detail_view	—	Switch Detail view to Device Chain
/live/view/focus_browser	—	Show the browser
/live/view/get/focused_document_view	—	Reply: "Session" or "Arranger"

---

Application

Address	Args	Reply	Description
/live/application/get/version	—	major minor build	Live version as three integers
/live/application/get/average_process_usage	—	float	CPU average usage (0–1)
/live/application/get/peak_process_usage	—	float	CPU peak usage (0–1)

---

Browser

Content browsing and loading. No index required.

Category listings

Returns a flat list of item names at the top level of each category.

Address	Reply	Description
/live/browser/get/audio_effects	string…	Audio effect names
/live/browser/get/instruments	string…	Instrument names
/live/browser/get/midi_effects	string…	MIDI effect names
/live/browser/get/samples	string…	Sample names
/live/browser/get/sounds	string…	Sound names
/live/browser/get/clips	string…	Clip names
/live/browser/get/packs	string…	Pack names
/live/browser/get/plugins	string…	Plugin names

Loading

Address	Args	Description
/live/browser/load_item	path_part [path_part …]	Load item by hierarchical path. Each argument narrows the search one level deep. Searches all categories.
/live/browser/preview_item	path_part [path_part …]	Preview item without loading.
/live/browser/stop_preview	—	Stop audio preview.

Example — load a Wavetable preset:

/live/browser/load_item  "Instruments"  "Wavetable"  "Bass"  "Dark Bass.adv"

Hotswap

Address	Args	Reply	Description
/live/browser/get/hotswap_target	—	string	Name of the current hotswap target device, or ""
/live/browser/begin_hotswap	track_index device_index	—	Set hotswap target to a specific device

---

Groove

Controls the global groove pool.

Address	Args	Reply	Description
/live/groove/get/grooves	—	string…	Names of all grooves in the pool
/live/groove/get/amount	groove_name	groove_name float	Groove intensity (0–1)
/live/groove/set/amount	groove_name float	—	Set groove intensity

Assign a groove to a specific clip via /live/clip/set/groove and /live/clip/get/groove.

---

Development setup

# Create the venv (already committed to .venv/ location)
python -m venv .venv

# Activate (Windows PowerShell)
.venv\Scripts\Activate.ps1

# Activate (macOS / Linux)
source .venv/bin/activate

# Install dev tools (python-osc for testing, pytest)
pip install -e ".[dev]"

The runtime code (AbletonOSC/) has no external dependencies and runs as-is inside Ableton's embedded Python 3.x.

---

Architecture

AbletonOSC/
├── __init__.py          create_instance() — Ableton's entry point
├── manager.py           Manager(ControlSurface) — owns OSC server and all handlers
├── osc_server.py        Pure-Python UDP OSC encode/decode; non-blocking poll
├── handler.py           AbletonOSCHandler base class
├── song.py              SongHandler      /live/song/*
├── track.py             TrackHandler     /live/track/*
├── return_track.py      ReturnTrackHandler  /live/return_track/*
├── clip.py              ClipHandler      /live/clip/*
├── clip_slot.py         ClipSlotHandler  /live/clip_slot/*
├── device.py            DeviceHandler    /live/device/*  /live/device/chain/*
├── scene.py             SceneHandler     /live/scene/*
├── view.py              ViewHandler      /live/view/*
├── application.py       ApplicationHandler  /live/application/*
├── browser.py           BrowserHandler   /live/browser/*
└── groove.py            GrooveHandler    /live/groove/*

Tick loop

Ableton's embedded Python does not support threading. The OSC server uses a non-blocking UDP socket and is polled by overriding ControlSurface.update_display(), which Live calls approximately every 100 ms.

Listener lifecycle

Each start_listen call stores (remove_fn, callback) in handler._listener_store keyed by a string like "track.2.mute". clear_listeners() iterates the store and detaches everything — called automatically on script disconnect and on /live/api/reload.

Handler base class

AbletonOSCHandler provides:

• _add(address, callback) — register an OSC handler
• _send(address, args) — push an unsolicited message to the last-seen client
• _register_listener(key, target, prop, notify_address, prefix) — attach a Live listener that calls add_<prop>_listener() and pushes the value on change
• _remove_listener(key) — detach a specific listener
• clear_listeners() — detach all listeners registered by this handler

Adding a new handler

1. Create AbletonOSC/my_handler.py subclassing AbletonOSCHandler.
2. Override init_api() and call self._add(address, callback) for each endpoint.
3. Import and instantiate in manager.py's _setup_handlers().