SuperAPI AI Directory

m4l-py2max-tooling

Coding & development

View repository

Updated 10-16 03:41

About this skill

Programmatic M4L Authoring with py2max

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

  1. 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).
  2. Use py2max's add_* helpers — let it manage IDs, inlet counts, outlettypes.
  3. Lay out presentation with presentation_rects inside the 169-px box. Use a layout helper or compute manually with m4l-presentation-layout's safe-bounds checker.
  4. Inject project block via ensure_amxd_project_block.
  5. Write .amxd via write_amxd.
  6. Drop the .amxd into the User Library folder for the device type (see m4l-amxd-conversion §7).
  7. Drag onto a track in Live to test load.
  8. Right-click → Open Max Window to debug (see m4l-debugging §2).
  9. 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/outlettype for every object class.
  • Build the project block with the correct amxdtype FOURCC integer.
  • Implement the 36-byte mixed-endian .amxd header 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/dire trailer.
  • 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 1 keeps JSON key order stable across saves — add as a message to the patcher.
  • Use Ableton/maxdevtools/maxdiff/amxd_textconv.py to produce readable diffs of .amxd in 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/numoutlets manually for those.
  • py2max doesn't yet support every nuance of the live.banks / parameterbanks structure — 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.