DOCSEARCHbyAlgolia
Submit Docs

AbletonOSC Documentation

repository·master·Indexed 21 days ago

https://github.com/ideoforms/abletonosc

A MIDI remote script for Ableton Live 11 and above that provides an Open Sound Control (OSC) interface to control the full Live Object Model (LOM) API. It enables remote management of playback, session structure, tracks, clips, and UI selection via inbound port 11000 and outbound port 11001.

Tokens
11K
Snippets
20
Records
31
Agent score
24%

What's inside AbletonOSC

  1. Understand the Song API

    master

    The Song API is the top-level interface for controlling an Ableton Live session. It allows you to manage playback (start/stop), manipulate the session structure (create/delete tracks, scenes, and cue points), and control global parameters like tempo, metronome, and time signature.

    Key capabilities include:

    • Playback Control: Start, stop, resume, and tap tempo.
    • Session Manipulation: Create/delete audio, MIDI, and return tracks; create/delete/duplicate scenes.
    • Navigation: Jump to specific cue points or move by a specified number of beats.
    • Global Settings: Get or set tempo, loop settings, and time signatures.

  2. Track API Overview

    master
    The Track API allows you to control and query audio, MIDI, return, or master tracks in Ableton Live. You can manipulate track parameters like volume, panning, sends, mute, and solo, or listen for active clip slots. It also provides capabilities to query devices on a track and retrieve clip information from both Session and Arrangement views.

  3. Listen for Track property changes

    master
    You can subscribe to changes for any Track property by calling the /live/track/start_listen/<property> address with the target track_index. When the property changes, AbletonOSC will send responses to /live/track/get/<property> containing the <track_index> and the new <property_value>.

  4. Configure OSC ports and usage patterns

    master

    AbletonOSC operates using two specific ports:

    • Listening (Inbound): Port 11000
    • Replies (Outbound): Port 11001 (replies are sent to the IP address of the originating message).

    Wildcard Queries

    You can use OSC wildcard patterns when querying properties. For example, to query all properties of a specific clip on a specific track, use: /live/clip/get/* 0 0 (where 0 0 represents track 0, clip 0).

    /live/clip/get/* 0 0

  5. Install AbletonOSC as a Remote Script

    master

    AbletonOSC is a MIDI remote script that exposes the Ableton Live Object Model (LOM) via OSC. It requires Ableton Live 11 or above.

    Installation Steps

    1. Download the repository ZIP and unzip it.
    2. Rename the extracted folder AbletonOSC-master to AbletonOSC.
    3. Copy the AbletonOSC folder to your Ableton User Library Remote Scripts directory:
      • Windows: \Users\[username]\Documents\Ableton\User Library\Remote Scripts
      • macOS: Macintosh HD/Users/[username]/Music/Ableton/User Library/Remote Scripts
    4. Restart Ableton Live.
    5. In Live, go to Preferences > Link / Tempo / MIDI and select AbletonOSC from the Control Surface dropdown.

    Once active, Live will display: AbletonOSC: Listening for OSC on port 11000.

    Windows: \Users\[username]\Documents\Ableton\User Library\Remote Scripts
macOS: Macintosh HD/Users/[username]/Music/Ableton/User Library/Remote Scripts

  6. Send OSC queries using the run-console.py utility

    master

    The run-console.py utility is a command-line tool included with the framework for quickly sending OSC queries to AbletonOSC without writing a full script.

    Usage:

    1. Run the script:
      ./run-console.py
    2. Once the console is active, enter commands using the /live/osc/command [params] format.

    Example Session:

    (1653)(AbletonOSC)$ ./run-console.py
AbletonOSC command console
Usage: /live/osc/command [params]
>>> /live/song/set/tempo 123.0
>>> /live/song/get/tempo
(123.0,)
>>> /live/song/get/track_names
('1-MIDI', '2-MIDI', '3-Audio', '4-Audio')

  7. Use the Clip Slot API to manage clips

    master

    The Clip Slot API allows you to interact with individual clip slots within Ableton Live. You can use these endpoints to fire clips, create or delete clips, check for clip existence, manage stop buttons, and duplicate clips between slots.

    Most endpoints require track_index and clip_index to identify the specific slot.

    | Address | Query params | Response params | Description |
|:---|:---|:---|:---|
| /live/clip_slot/fire | track_index, clip_index | | Fire play/pause of the specified clip slot |
| /live/clip_slot/create_clip | track_index, clip_index, length | | Create a clip in the slot |
| /live/clip_slot/delete_clip | track_index, clip_index | | Delete the clip in the slot |
| /live/clip_slot/get/has_clip | track_index, clip_index | track_index, clip_index, has_clip | Query whether the slot has a clip |
| /live/clip_slot/get/has_stop_button | track_index, clip_index | track_index, clip_index, has_stop_button | Query whether the slot has a stop button |
| /live/clip_slot/set/has_stop_button | track_index, clip_index, has_stop_button | | Add or remove stop button (1=on, 0=off) |
| /live/clip_slot/duplicate_clip_to | track_index, clip_index, target_track_index, target_clip_index | | Duplicate the clip to an empty target clip slot |

  8. Use the Scene API to trigger and manage scenes

    master

    The Scene API allows you to trigger rows of clips (scenes) and manage their properties like name, color, tempo, and time signature.

    Triggering Scenes

    • /live/scene/fire <scene_id>: Trigger a specific scene.
    • /live/scene/fire_as_selected <scene_id>: Trigger a scene and select the next one.
    • /live/scene/fire_selected: Trigger the currently selected scene and select the next one.

    Managing Scene Properties

    Properties can be queried using getters or modified using setters.

    Available Properties:

    • name
    • color / color_index
    • is_empty
    • is_triggered
    • tempo / tempo_enabled
    • time_signature_numerator / time_signature_denominator / time_signature_enabled

    Listening for Scene Changes

    You can subscribe to property changes by calling /live/scene/start_listen/<property> <scene_index>. Updates will be sent to /live/scene/get/<property> with the format <scene_index> <property_value>.

    ### Scene methods
| Address                         | Query params | Response params | Description             |
|:--------------------------------|:-------------|:----------------|:------------------------|
| /live/scene/fire                | scene_id     |                 | Trigger the given scene |
| /live/scene/fire_as_selected    | scene_id     |                 | Trigger the scene and select the next scene |
| /live/scene/fire_selected       |              |                 | Trigger the selected scene and select the next scene |

  9. Clip API Reference

    master

    The Clip API allows you to control and query audio or MIDI clips in Ableton Live. You can manage playback (start/stop), modify MIDI notes, adjust clip properties like gain, pitch, color, and name, and monitor clip states such as playing position or recording status.

    Playback Control

    • Start clip: /live/clip/fire (requires track_id, clip_id)
    • Stop clip: /live/clip/stop (requires track_id, clip_id)
    • Duplicate loop: /live/clip/duplicate_loop (requires track_id, clip_id)

    MIDI Note Manipulation

    • Query notes: /live/clip/get/notes (requires track_id, clip_id; optional start_pitch, pitch_span, start_time, time_span)
    • Add notes: /live/clip/add/notes (requires track_id, clip_id, pitch, start_time, duration, velocity, mute)
    • Remove notes: /live/clip/remove/notes (requires start_pitch, pitch_span, start_time, time_span. If no ranges are specified, all notes are removed.)

    Clip Properties

    • Name: Get via /live/clip/get/name, Set via /live/clip/set/name (requires track_id, clip_id, name)
    • Gain: Get via /live/clip/get/gain, Set via /live/clip/set/gain (requires track_id, clip_id, gain)
    • Color: Get via /live/clip/get/color or /live/clip/get/color_index (0-69), Set via /live/clip/set/color or /live/clip/set/color_index (0-69)
    • Pitch: Coarse re-pitch via /live/clip/get/pitch_coarse and /live/clip/set/pitch_coarse (in semitones); Fine re-pitch via /live/clip/get/pitch_fine and /live/clip/set/pitch_fine (in cents)
    • Launch Mode: Get via /live/clip/get/launch_mode, Set via /live/clip/set/launch_mode (0=Trigger, 1=Gate, 2=Toggle, 3=Repeat)
    • Launch Quantization: Get via /live/clip/get/launch_quantization, Set via /live/clip/set/launch_quantization (0=Global, 1=None, 2=8Bars, ..., 14=1/32)
    • Warp Mode: Get via /live/clip/get/warp_mode, Set via /live/clip/set/warp_mode (0=Beats, 1=Tones, 2=Texture, 3=Re-Pitch, 4=Complex, 5=Invalid/Error, 6=Pro)
    • Mute/Legato/Ram Mode: Get and Set via /live/clip/get/muted / /live/clip/set/muted, /live/clip/get/legato / /live/clip/set/legato, and /live/clip/get/ram_mode / /live/clip/set/ram_mode (0=False, 1=True)

    Monitoring and State

    • Playing Position: Get current position via /live/clip/get/playing_position. To receive continuous updates, use /live/clip/start_listen/playing_position and stop with /live/clip/stop_listen/playing_position.
    • Clip Type: Query if audio via /live/clip/get/is_audio_clip or MIDI via /live/clip/get/is_midi_clip.
    • Playback State: Query is_playing, is_recording, is_overdubbing, or will_record_on_start.
    • Looping: Get/Set loop_start and loop_end via /live/clip/get/loop_start / /live/clip/set/loop_start and /live/clip/get/loop_end / /live/clip/set/loop_end.

  10. Use Song methods to control playback and session structure

    master

    The Song API provides several methods to perform actions in Ableton Live. These are accessed via specific OSC addresses.

    Common Playback Methods

    • /live/song/start_playing: Start session playback.
    • /live/song/stop_playing: Stop session playback.
    • /live/song/continue_playing: Resume session playback.
    • /live/song/stop_all_clips: Stop all clips from playing.
    • /live/song/tap_tempo: Mimics a tap of the "Tap Tempo" button.

    Common Session Management Methods

    • /live/song/create_audio_track (param: index): Create a new audio track. Use -1 for the end of the list.
    • /live/song/create_midi_track (param: index): Create a new MIDI track. Use -1 for the end of the list.
    • /live/song/create_scene (param: index): Create a new scene. Use -1 for the end of the list.
    • /live/song/delete_track (param: track_index): Delete a track.
    • /live/song/delete_scene (param: scene_index): Delete a scene.
    • /live/song/undo: Undo the last operation.
    • /live/song/redo: Redo the last undone operation.

  11. Map MIDI CC to Live parameters with MidiMap API

    master

    The MidiMap API allows you to create assignments between MIDI Control Change (CC) messages and Ableton Live parameters.

    Use the following address to create a mapping: /live/midimap/map_cc <track_id> <device_id> <param_id> <channel> <cc>

    Important Note on Channels: Channels are zero-indexed to maintain consistency with Live's internal API. For example, to map MIDI channel 1, use 0 as the channel parameter.

    | Address                | Query params | Response params | Description             |
|:-----------------------|:-------------|:----------------|:------------------------|
| /live/midimap/map_cc   | track_id, device_id, param_id, channel, cc     |  | Create an assignment such that control change `cc` on channel `channel` will control the specified parameter. |

  12. Listen for beat events

    master

    To receive a status message on every beat, use the beat listening API. This is useful for synchronizing external hardware or UI elements with the Ableton transport.

    1. Start listening: Call /live/song/start_listen/beat.
    2. Receive updates: Every beat, a response is sent to /live/song/get/beat containing an integer representing the current beat number.
    3. Stop listening: Call /live/song/stop_listen/beat to cease updates.