SuperAPI AI Directory

m4l-live-api

Coding & development

View repository

Updated 10-16 03:41

About this skill

Max for Live: Live API and live.* Objects

The Live API is asynchronous, single-threaded (low priority), deferred, and only available inside an .amxd. From standalone Max, LiveAPI is undefined.

1. Live Object Model (LOM) — the tree

Four root objects for absolute paths:

Root Class Purpose
live_app Application Live itself: version, control surfaces, browser
live_set Song Current Set: tracks, scenes, transport, view
control_surfaces N ControlSurface Nth Control Surface from Preferences
this_device Device The Max device containing this object

Canonical nest:

live_app
└── view (Application.View)

live_set                                  (Song)
├── view (Song.View)
│    ├── selected_track  (or id 0)
│    ├── selected_scene
│    ├── selected_parameter
│    ├── detail_clip
│    ├── highlighted_clip_slot
│    ├── draw_mode  (0 arrow / 1 pencil)
│    └── follow_song
├── tracks N (Track)
│    ├── view (Track.View)
│    ├── clip_slots K (ClipSlot)
│    │    └── clip (Clip; id 0 if empty)
│    ├── devices M (Device, includes mixer device)
│    │    ├── view (is_collapsed)
│    │    ├── parameters L (DeviceParameter; only automatable ones)
│    │    ├── chains P (Chain; rack-only)
│    │    └── return_chains Q
│    └── mixer_device (volume, panning, sends N)
├── return_tracks N (Track)
├── master_track (Track)
├── scenes N (Scene: name, tempo, color, is_triggered)
├── cue_points N (CuePoint: name, time, jump())
├── groove_pool (Live 11+)
└── tuning_system (Live 12+)

Every object also has a canonical_parent child — useful to walk from this_device up to its Track: goto this_device canonical_parent.

Different paths can resolve to the same object — live_set view selected_track and live_set tracks 3 are the same when the fourth track is selected.

Track properties

name, color (0x00rrggbb), arm, mute, solo, has_audio_input, has_audio_output, has_midi_input, has_midi_output, is_foldable, fold_state, is_grouped. Functions: stop_all_clips(), delete_clip(clip), jump_in_running_session_clip(beats).

Clip properties

name, color, looping, loop_start, loop_end, start_marker, end_marker, signature_numerator, is_midi_clip, is_audio_clip, is_playing, is_triggered, gain (0..1, audio only), pitch_coarse (-48..48), pitch_fine (-50..49), warping, warp_mode. Note APIs: get_notes_extended, get_all_notes_extended, apply_note_modifications, add_new_notes, remove_notes_extended.

ClipSlot

has_clip, is_playing, is_triggered, playing_status, has_stop_button, controls_other_clips. Functions: fire(record_length, launch_quantization), stop(), create_clip(length_in_beats) (MIDI only), delete_clip(), duplicate_clip_to(target).

DeviceParameter

value (get/set/observe), min, max, default_value, is_enabled, is_quantized, name, automation_state (0 none / 1 active / 2 overridden). Feed the id into live.remote~ for audio-rate modulation, or use live.object set value <v> for control rate.

2. live.path — navigation

Send path … or goto …; emits id NN:

path live_set tracks 0 devices 0
path live_set tracks 2 clip_slots 0 clip
path live_set view selected_track
path this_device
path this_device canonical_parent

Outlets:

  • Left: emits id NN for goto/bang/getid. For dynamic paths like live_set view selected_track, does NOT re-emit when underlying object changes.
  • Middle (follow): emits id NN whenever the object at the path changes — re-bind selection-tracking.
  • Right: replies to getpath, getchildren, getcount.

id 0 = no object. Always gate downstream traffic.

3. live.object — get / set / call

Right inlet takes id NN. Left outlet emits responses.

Message Meaning
id NN Set current object; id 0 ignores all subsequent
get <property> Read property; result <property> <value>
set <property> v Write
call <fn> [args] Invoke LOM function; result at left outlet
goto <path> Re-navigate
getproperty Describe currently selected property
getcount <child> Count children
getpath Emit canonical path
gettype Emit class name
getinfo Long description: id, type, children, properties, fns
info Dump multi-line description

The "id" prefix: outputs always include the symbol id (e.g., id 17). Route via [route id] to strip it before using.

set is async — reading immediately after writing may return stale. Either observe via live.observer, or [deferlow] the read.

Persistent Mapping (Inspector option) makes the id survive saves/restores starting Live 8.2.2. Without it, ids are session-scoped.

4. live.observer — listen for changes

Send property <name> to start observing; receive value at left outlet on every change.

property name        ; scalar
property clip_slots  ; list of ids
property mute        ; bool

Critical rule — from inside a notification callback, you CANNOT mutate Live state:

Console error: "Changes cannot be triggered by notifications"

Fix: insert [deferlow] between observer outlet and any set/call.

Not all properties are observable — check each LOM entry's observe access.

5. live.thisdevice — the only legal init bang

NEVER use loadbang for Live API code. loadbang fires before Live finishes binding the device, and the API returns id 0.

live.thisdevice outlets:

  • Left: bang when device is opened AND fully initialized (LiveAPI guaranteed ready).
  • Middle: 1/0 when device enabled/disabled.
  • Right: 1/0 preview mode; also receives getstate reply.

Wire the left outlet into whatever initialization you need (including js objects that construct LiveAPI).

Console error if you forget:

live.object: Live API is not initialized, use live.thisdevice to determine when initialization is complete

6. live.remote~ — sample-accurate parameter modulation

Right inlet: DeviceParameter id. Left inlet: messages OR audio signal — applied sample-accurately with one audio-buffer latency.

Key behaviors:

  • Bypasses automation and undo. Parameter shows "disabled" in Live while remote~ is active, like Macro mapping.
  • normalized attribute auto-scales 0..1 input to parameter's min/max.
  • Only DeviceParameter targets — device knobs, mixer volume/pan, sends.

Use live.remote~ for audio-rate / sample-accurate. Use live.object set value for control-rate writes that should respect automation.

7. Live UI / parameter objects — the inspector block

Every live.* UI object exposes the unified Parameter inspector tab. To make a UI box an automatable Live parameter in JSON:

Required fields per box

{ "box": {
    "id": "obj-N",
    "maxclass": "live.dial",
    "numinlets": 1, "numoutlets": 2, "outlettype": ["", "float"],
    "patching_rect": [40.0, 40.0, 35.0, 48.0],
    "presentation": 1, "presentation_rect": [16, 28, 40, 52],
    "parameter_enable": 1,
    "varname": "freq",
    "saved_attribute_attributes": {
      "valueof": {
        "parameter_longname":  "freq",
        "parameter_shortname": "Freq",
        "parameter_type":      0,
        "parameter_initial_enable": 1,
        "parameter_initial":   [440.0],
        "parameter_mmin":      20.0,
        "parameter_mmax":      20000.0,
        "parameter_unitstyle": 2,
        "parameter_exponent":  1.0,
        "parameter_modmode":   1,
        "parameter_invisible": 0
      }
    }
} }

valueof field reference

Key Type Meaning
parameter_longname string UNIQUE long name. Live identifies the param by this.
parameter_shortname string Display label in Live (5-7 chars typical)
parameter_type int 0 Float, 1 Int, 2 Enum, 3 Blob
parameter_initial_enable 0/1 Apply Initial on instantiation
parameter_initial array Initial value, e.g. [0.5]
parameter_mmin float Min (param_range alt: pair)
parameter_mmax float Max
parameter_unitstyle int 0 Int, 1 Float, 2 Hertz, 3 deciBel, 4 %, 5 Pan, 6 Semitones, 7 MIDI, 8 Custom, 9 Native, 10 Time
parameter_units string sprintf format when unitstyle = 8 Custom
parameter_exponent float Non-linear taper (>1 emphasizes low values)
parameter_steps int Discretization
parameter_modmode int 0 None / 1 Unipolar / 2 Bipolar / 3 Additive / 4 Absolute
parameter_invisible 0/1 0 visible, 1 hidden from Live's parameter list
parameter_enum array Enum value names when type = 2

Parameter Visibility — the underused dropdown

In the Inspector ("Parameter Visibility"), three modes — but the JSON encoding is split between two fields:

  • Automated and Stored — appears in automation lanes, MIDI-mappable, saved with set/preset. Standard for user-facing params.
  • Stored Only — saved with set/preset but NOT automatable. For state knobs.
  • Hidden — neither. Use for internal/computed parameters you drive from the patch (avoids undo-history spam).

The default for fresh live.* objects is "Stored Only" — you MUST flip to "Automated and Stored" for normal user-facing parameters. Forgetting this is a top LLM mistake.

Modulation Mode

parameter_modmode controls how clip envelopes modulate the param:

  • 0 None → can't be modulated
  • 1 Unipolar → 0..1 added on top
  • 2 Bipolar → -1..1 centered (most common for continuous floats)
  • 3 Additive → adds raw modulation value to the current value
  • 4 Absolute → modulation overrides current value (common for int/enum)

Default Modulation Mode = None → silently disables clip-envelope modulation. Pick Bipolar for floats or Absolute for ints when you want envelopes.

Int range cap

parameter_type: 1 (Int) is capped at 256 values (0–255). For larger integer ranges, use parameter_type: 0 (Float) + parameter_unitstyle: 0 (Int unit style).

Long Name uniqueness

Long Name must be unique across the entire device's parameter set. Max appends [1], [2] to duplicates from abstractions. Never ship a device with [N] suffixes — they break automation persistence across updates. Live identifies parameters by Long Name across saves; renaming a published Long Name breaks user automation and preset recall.

8. Per-object specifics

Object Purpose
live.dial Circular control. Has exponent + steps. Most common.
live.numbox Numeric entry. Precise int/float. Easy to forget parameter_enable: 1.
live.slider orientation: 0 vertical (default), 1 horizontal.
live.text mode 0 button (bang on release), mode 1 toggle. Appearance: Default/Label/LCD.
live.tab Radio/tab selector (Enum). mode 0 Equal Spaced, 1 Proportional.
live.menu Pop-up enum menu. Range/Enum = space-delimited names (quote items with spaces).
live.toggle Boolean.
live.button Momentary; bang on click. transition controls when bangs fire under automation.
live.step Multi-sequence step sequencer (pitch 0-127, vel, dur).
live.grid 2-D matrix UI.
live.drop File drop target. Left out = path symbol.
live.line Visual divider line. Not a parameter, no outlets.
live.gain~ Audio-rate fader with metering. Parameter-aware. Default -70 to +6 dB.
live.meter~ Display-only signal-level meter. Peak, no RMS mode.
live.scope~ Display-only oscilloscope. History or Trigger modes.
live.comment Text label (parameter-aware so it can show Live's selected param name).

9. live.banks — Push / hardware bank layout

Defines named banks of parameters shown on Push and control surfaces. Each bank holds up to 8 encoder slots.

"parameterbanks": {
  "0": { "index": 0, "name": "Main",
         "parameters": ["freq", "reso", "drive", "mix", "-", "-", "-", "-"] }
}

"-" = empty slot. Runtime messages: new, edit, delete, getcount, getname, getparameters.

10. MIDI inside M4L

Device-type templates dictate I/O:

  • MIDI Effect (mmmm): midiin → midiout by default. Use notein/noteout, ctlin/ctlout, bendin/bendout, pgmin/pgmout, or raw midiin/midiout. The track supplies the MIDI port — don't configure ports inside the device.
  • Instrument (iiii): midiin → plugout~ (audio out only).
  • Audio Effect (aaaa): plugin~ → plugout~ (no MIDI).

Polyphony uses poly~ with a per-voice patcher; midiparse + makenote + voice-stealing inside.

11. Audio I/O

  • plugin~ — receives audio from upstream device in chain. Default 2 channels.
  • plugout~ — sends audio downstream. Default 2 channels.
  • Multichannel >2 between adjacent devices is unreliable on Live <11. On Live 11+, use mc.* objects.
  • mc.* (multichannel) objects work inside the device for voice management (mc.cycle~ 8, etc.).

12. Common API gotchas

  1. Init only after live.thisdevice bang. Never use loadbang for LiveAPI traffic.
  2. id 0 = nothing. Always gate downstream — [route id] then [select 0] to detect null.
  3. "Changes cannot be triggered by notifications" → insert [deferlow] between observer and any set/call.
  4. live.object set is async — observe or defer the read.
  5. Long Name uniqueness — Max appends [N] to duplicates from abstractions; ship without suffixes.
  6. Scripting name (varname) must be unique if using live.banks or pattr.
  7. Parameter Visibility = "Automated and Stored" for user-facing; "Hidden" for internal-only.
  8. Modulation Mode = None silently kills clip-envelope modulation. Pick Bipolar / Absolute.
  9. Int type is 0–255; for larger use Float + Int unit style.
  10. LiveAPI undefined outside M4L. Don't try to use in standalone Max.
  11. IDs are session-scoped — never persist. Re-resolve from path at load.
  12. Hot-reload re-bangs live.thisdevice and re-binds observers. Use pattr/pattrstorage for state.
  13. this_device is essential. Hardcoding live_set tracks 0 devices 0 breaks when the user moves the device.
  14. Defer Automation Output / Update Limit (ms) — set in Inspector if automation causes CPU spikes.
  15. Freeze before distribution.

13. Worked example: bind to selected_track and observe name

[live.thisdevice]
       |
       v
[bang]
       |
       v
[path live_set view selected_track]
   |       | (middle = follow notification)
   |       \--------\
   v                v
[route id]      [route id]
   |
   v
[live.observer]   <-- right inlet (id)
[property name]   <-- left inlet (start observing)
   |
   | left outlet emits "name <value>" on every change
   v
[deferlow]
   v
[print SELTRACK]

In JS (preferred for any non-trivial logic — see m4l-javascript):

function bang() {
    // called from live.thisdevice
    this.watcher = new LiveAPI(function(args) {
        if (args[0] == "name") post("track name:", args[1], "\n");
    }, "live_set view selected_track");
    this.watcher.property = "name";
}