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 NNforgoto/bang/getid. For dynamic paths likelive_set view selected_track, does NOT re-emit when underlying object changes. - Middle (follow): emits
id NNwhenever 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
getstatereply.
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.
normalizedattribute 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 → midioutby default. Usenotein/noteout,ctlin/ctlout,bendin/bendout,pgmin/pgmout, or rawmidiin/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
- Init only after
live.thisdevicebang. Never useloadbangfor LiveAPI traffic. id 0= nothing. Always gate downstream —[route id]then[select 0]to detect null.- "Changes cannot be triggered by notifications" → insert
[deferlow]between observer and anyset/call. live.object setis async — observe or defer the read.- Long Name uniqueness — Max appends
[N]to duplicates from abstractions; ship without suffixes. - Scripting name (
varname) must be unique if usinglive.banksorpattr. - Parameter Visibility = "Automated and Stored" for user-facing; "Hidden" for internal-only.
- Modulation Mode = None silently kills clip-envelope modulation. Pick Bipolar / Absolute.
- Int type is 0–255; for larger use Float + Int unit style.
- LiveAPI undefined outside M4L. Don't try to use in standalone Max.
- IDs are session-scoped — never persist. Re-resolve from path at load.
- Hot-reload re-bangs
live.thisdeviceand re-binds observers. Usepattr/pattrstoragefor state. this_deviceis essential. Hardcodinglive_set tracks 0 devices 0breaks when the user moves the device.- Defer Automation Output / Update Limit (ms) — set in Inspector if automation causes CPU spikes.
- 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";
}