SuperAPI AI Directory

m4l-overview

General & other

View repository

Updated 10-16 03:41

About this skill

Max for Live — Overview & Skill Router

Max for Live (M4L) is Cycling '74 Max embedded in Ableton Live. Devices are saved as .amxd files (a thin binary container around a .maxpat JSON patcher). LLMs often fail at M4L because the format is partly undocumented, the GUI has a strict 169-pixel height cap, the Live API is async/deferred with idiosyncratic init timing, and a handful of fields (project block, FOURCC, NUL termination, parameter_enable) silently break devices when wrong.

Before doing any M4L work, decide what you're being asked to do and load the matching skill(s). Don't try to recall format details from memory — read the SKILL.md for the relevant area.

Three device types (FOURCC tag → required I/O objects)

Type FOURCC Required objects User Library subfolder (macOS)
Audio Effect aaaa plugin~ → DSP → plugout~ ~/Music/Ableton/User Library/Presets/Audio Effects/Max Audio Effect/
Instrument iiii midiin → voice engine (poly~) → plugout~ ~/Music/Ableton/User Library/Presets/Instruments/Max Instrument/
MIDI Effect mmmm midiin → transform → midiout ~/Music/Ableton/User Library/Presets/MIDI Effects/Max MIDI Effect/

Windows replaces ~/Music/Ableton with %USERPROFILE%\Documents\Ableton.

When to load which sub-skill

Task Skill to load
Generate or edit raw .maxpat JSON m4l-maxpat-format
Convert .maxpat ↔ .amxd, build a device wrapper, debug "could not open" m4l-amxd-conversion
GUI overflow, presentation layout, knob row, devicewidth, presentation_rect m4l-presentation-layout
Talk to Ableton (tracks/clips/transport), expose Live parameters, mapping m4l-live-api
Author JS inside js/v8/jsui/v8ui objects m4l-javascript
Sample-accurate DSP, single-sample feedback filters, GenExpr m4l-gen
Device fails to load, weird errors, Max Console workflow m4l-debugging
Programmatic device generation (Python) m4l-py2max-tooling

Most non-trivial tasks need 2-3 of these together (e.g., writing a 4-knob audio effect needs m4l-maxpat-format + m4l-presentation-layout + m4l-live-api for the parameter inspector block).

Top 12 rules LLMs forget

  1. The device is 169 pixels tall, period. Anything with presentation_rect's y+h > 169 is clipped. See m4l-presentation-layout.
  2. Use integer pixel coordinates in presentation_rect. Floats render blurry on non-Retina.
  3. openinpresentation: 1 at patcher level — without it, Live's view diverges from your editor view.
  4. Every visible box needs "presentation": 1 AND presentation_rect; presence of one without the other = invisible in Live.
  5. .amxd is NOT just a renamed .maxpat. It has a 36-byte mixed-endian header + IFF-style trailer. See m4l-amxd-conversion.
  6. The .maxpat inside an .amxd must contain a project block or Max prints "a project without a name is like a day without sunshine. fatal." and refuses to load.
  7. live.thisdevice, not loadbang, for any init that touches the Live API. loadbang fires before Live finishes binding the device.
  8. live.numbox ≠ number. Only live.* objects can become Live parameters. A number cannot be automated or MIDI-mapped.
  9. parameter_enable: 1 and a saved_attribute_attributes.valueof block are both required to make a live.* object an automatable Live parameter. Long Name must be unique per device.
  10. Parameter Visibility must be "Automated and Stored" to appear in Live's automation/mapping. "Stored Only" saves but can't be automated.
  11. Modulation Mode = None disables clip-envelope modulation. Pick Bipolar (float) or Absolute (int) when you want envelopes.
  12. Don't hand-write JSON if you can avoid it. Use py2max (Python) to build devices programmatically — it validates inlet/outlet counts and writes a proper .amxd container. See m4l-py2max-tooling.

Recommended overall workflow for an LLM authoring a device

  1. Start from a template — copy templates/minimal-{audio-effect,instrument,midi-effect}.maxpat from m4l-maxpat-format. Modify, don't construct from scratch.
  2. Place UI in presentation mode with integer coordinates inside the 169 px box. Use the reference layouts in m4l-presentation-layout.
  3. Wire DSP / MIDI with the device-type-correct I/O objects.
  4. Set up parameters with parameter_enable: 1 + the saved_attribute_attributes.valueof block. See m4l-live-api.
  5. Pack to .amxd via py2max's write_amxd or the standalone packer script. See m4l-amxd-conversion.
  6. Test load by dragging into Live (double-click does NOT load it). Right-click device title → Open Max Window to see errors. See m4l-debugging.

File extensions cheatsheet

  • .maxpat — patcher JSON, opens in standalone Max
  • .amxd — Max for Live device (binary container with embedded .maxpat)
  • .mxo / .mxe64 — compiled externals (Mac / Windows)
  • .maxproj — Max Project bundle
  • .maxhelp — help patcher (same JSON format as .maxpat)
  • .gendsp — Gen patcher
  • .rnbopat — RNBO patcher

What MIDI Tools are (Live 12)

Live 12 added a fourth device family for the MIDI Generators / Transformations panel. FOURCCs: nagg (Generator) and natt (Transformation). User Library path: ~/Music/Ableton/User Library/Presets/MIDI Tools/Max MIDI Tool/. These are a special case — most "make me an M4L device" requests are for the classic three types.