Direct .maxpat JSON authoring is fragile — wrong numinlets, malformed outlettype, missing project block, wrong FOURCC, wrong endianness in .amxd headers all silently break devices. Prefer Python libraries that already get this right.
1. The libraries
shakfu/py2max — primary choice
Python 3.9+ library for offline .maxpat/.maxhelp/.rbnopat generation, round-trip read/edit/save, SVG preview, M4L .amxd packer with the binary container correctly implemented, CLI, and a MaxRef DB of 1157 objects with inlet/outlet validation.
pip install py2max
# or from source
git clone https://github.com/shakfu/py2max
cd py2max && pip install -e .
URL: https://github.com/shakfu/py2max
Barnard-PL-Labs/MaxPyLang — higher-level DSL
Python package for metaprogramming Max — generate and edit Max patches from Python, explicitly targeted at "vibecoding of Max patches" with LLM coding agents.
pip install MaxPyLang
URL: https://github.com/Barnard-PL-Labs/MaxPyLang
Ableton/maxdevtools — official tools
Ableton's internal toolkit. Includes:
maxdiff/amxd_textconv.py— convert.amxd↔ readable diff text. The authoritative parser.m4l-production-guidelines/— markdown guide all M4L devs should read.patch-code-standard/— Ableton's internal style guide.cpu-reporter/— measure device CPU over time.
git clone https://github.com/Ableton/maxdevtools
python3 maxdiff/amxd_textconv.py path/to/device.amxd
URL: https://github.com/Ableton/maxdevtools
2. py2max — minimal device example
from py2max import Patcher
p = Patcher("MyAmp.maxpat")
p.openinpresentation = 1
p.devicewidth = 240
# I/O
plugin = p.add_textbox("plugin~", patching_rect=(40, 40, 60, 22))
plugout = p.add_textbox("plugout~ 2", patching_rect=(40, 200, 80, 22))
gain = p.add_textbox("*~ 0.5", patching_rect=(40, 120, 60, 22))
p.add_line(plugin, gain, outlet=0, inlet=0)
p.add_line(plugin, gain, outlet=1, inlet=0)
p.add_line(gain, plugout, outlet=0, inlet=0)
p.add_line(gain, plugout, outlet=0, inlet=1)
# UI in presentation mode
dial = p.add_dial(
longname="gain",
shortname="Gain",
parameter_type=0,
parameter_mmin=0.0,
parameter_mmax=1.0,
parameter_initial=[0.5],
patching_rect=(40, 300, 35, 48),
presentation_rect=(16, 28, 40, 85),
)
p.add_line(dial, gain, outlet=0, inlet=1)
p.save() # writes MyAmp.maxpat
py2max manages id allocation, sets numinlets/numoutlets/outlettype from the MaxRef DB, and validates connections.
3. py2max — pack to .amxd
from py2max.m4l import write_amxd, ensure_amxd_project_block
# After building the patcher dict (or loading one):
ensure_amxd_project_block(patcher_dict, device_type="audio_effect")
write_amxd("MyAmp.amxd", patcher_dict, device_type="audio_effect")
ensure_amxd_project_block injects the mandatory project block with correct amxdtype FOURCC. write_amxd builds the 36-byte mixed-endian header, NUL-terminates the JSON, and emits the IFF dlst/dire trailer — all the fiddly bits you don't want to hand-roll.
Device types: "audio_effect", "instrument", "midi_effect".
4. py2max — round-trip edits
Load an existing .maxpat, modify, save:
from py2max import Patcher
p = Patcher.from_file("Existing.maxpat")
# Change a parameter range
for box in p.boxes:
if box.maxclass == "live.dial" and box.varname == "freq":
box.saved_attribute_attributes["valueof"]["parameter_mmax"] = 5000.0
# Add a new comment
p.add_comment("Refactored 2026-06-13", patching_rect=(40, 400, 200, 20))
p.save("Existing_modified.maxpat")
For .amxd round-trip:
from py2max.m4l import read_amxd, write_amxd, ensure_amxd_project_block
device_type, patcher = read_amxd("Existing.amxd")
# ... edit patcher dict ...
ensure_amxd_project_block(patcher, device_type=device_type)
write_amxd("Existing_v2.amxd", patcher, device_type=device_type)
5. py2max — layout helpers
py2max ships utilities for grid-based placement:
from py2max.layout import HorizontalLayoutManager, GridLayoutManager
# Lay out 4 knobs horizontally in presentation
layout = HorizontalLayoutManager(
item_w=40, item_h=85, spacing=16, inset=(8, 28)
)
for i, name in enumerate(["gain", "tone", "drive", "mix"]):
x, y = layout.next()
p.add_dial(longname=name, shortname=name.title(),
presentation_rect=(x, y, 40, 85),
parameter_type=0, parameter_mmin=0, parameter_mmax=1,
parameter_initial=[0.5])
6. py2max — interactive browser server
Recent py2max ships an interactive server that previews patches in a browser as you edit Python:
py2max serve myscript.py
Opens a browser preview that hot-reloads on changes. Helpful for visual iteration.
7. py2max — MaxRef object validation
from py2max.maxref import MaxRef
ref = MaxRef()
info = ref.lookup("cycle~")
# info.numinlets, info.numoutlets, info.outlettypes
Use this to validate generated boxes before serialization — catches typos like cycle (no tilde, no such object) vs cycle~.
8. MaxPyLang — higher-level DSL alternative
If py2max feels too imperative, MaxPyLang offers a more declarative Python DSL for the same task. Quality is newer/less battle-tested but the abstraction is cleaner for LLM authoring.
import maxpylang as mx
with mx.Patcher("MyAmp", device_type="audio_effect") as p:
audio_in = p.plugin_tilde()
audio_out = p.plugout_tilde(channels=2)
knob = p.live_dial(longname="gain", min=0, max=1, init=0.5,
position=(16, 28, 40, 85))
p.connect(audio_in.out(0), knob, audio_out.in(0))
p.connect(audio_in.out(1), knob, audio_out.in(1))
p.save_as_amxd("MyAmp.amxd")
(API shape from the project README; verify against the latest docs.)
9. Recommended LLM authoring workflow with py2max
- Plan in Python — describe the device's I/O graph and parameters as a Python data structure (list of dials, list of internal objects, list of connections).
- Use py2max's
add_*helpers — let it manage IDs, inlet counts, outlettypes. - Lay out presentation with
presentation_rects inside the 169-px box. Use a layout helper or compute manually withm4l-presentation-layout's safe-bounds checker. - Inject
projectblock viaensure_amxd_project_block. - Write
.amxdviawrite_amxd. - Drop the
.amxdinto the User Library folder for the device type (seem4l-amxd-conversion§7). - Drag onto a track in Live to test load.
- Right-click → Open Max Window to debug (see
m4l-debugging§2). - Iterate in Python; re-run the script to regenerate; the loaded device updates if you save over the same path (Live picks it up only when re-dragged).
10. Why not write raw JSON?
You can. But you'll have to:
- Maintain a single ID counter manually across all boxes.
- Look up the correct
numinlets/numoutlets/outlettypefor every object class. - Build the
projectblock with the correctamxdtypeFOURCC integer. - Implement the 36-byte mixed-endian
.amxdheader with little-endian sizes at offsets 4 and 16 and big-endian at 24, 28, 32. - NUL-terminate the JSON precisely.
- Build the IFF
dlst/diretrailer. - Handle Mac classic epoch (1904-01-01 UTC) for
creationdate/modificationdate.
py2max does all of this. Use it.
11. Source-control hygiene for generated devices
- Commit the Python authoring script — that's the source of truth.
- Commit a sample built
.maxpat(text-diffable) but consider gitignoring.amxd(binary). ;max sortpatcherdictonsave 1keeps JSON key order stable across saves — add as a message to the patcher.- Use
Ableton/maxdevtools/maxdiff/amxd_textconv.pyto produce readable diffs of.amxdin code review.
12. Caveats
- py2max's MaxRef DB is large but not exhaustive — niche externals (third-party packages) may not be in it. Fall back to setting
numinlets/numoutletsmanually for those. - py2max doesn't yet support every nuance of the
live.banks/parameterbanksstructure — review the output JSON if you need Push bank layout. - Hand-edit + Max-save round-trip remains the gold standard for fixing weird format edge cases. py2max → Max-saved → Max-saved again normalizes anything py2max missed.