SuperAPI AI Directory

m4l-maxpat-format

Coding & development

View repository

Updated 10-16 03:41

About this skill

.maxpat JSON Format

The .maxpat is a single JSON object with one top-level key "patcher". UTF-8, no BOM, no JSON comments, no trailing commas, no NaN/Infinity. Max's parser is strict.

Numbers in coordinate fields are floats; in presentation_rect you MUST round to integers (sharp rendering — see m4l-presentation-layout).

1. Top-level patcher object — required keys

Emit all of these. Values shown are safe defaults:

{
  "patcher": {
    "fileversion": 1,
    "appversion": { "major": 8, "minor": 5, "revision": 5,
                    "architecture": "x64", "modernui": 1 },
    "classnamespace": "box",
    "rect": [85.0, 104.0, 640.0, 480.0],
    "bglocked": 0,
    "openinpresentation": 1,
    "default_fontsize": 12.0,
    "default_fontface": 0,
    "default_fontname": "Ableton Sans",
    "gridonopen": 1,
    "gridsize": [8.0, 8.0],
    "gridsnaponopen": 1,
    "objectsnaponopen": 1,
    "statusbarvisible": 2,
    "toolbarvisible": 1,
    "lefttoolbarpinned": 0,
    "toptoolbarpinned": 0,
    "righttoolbarpinned": 0,
    "bottomtoolbarpinned": 0,
    "toolbars_unpinned_last_save": 0,
    "tallnewobj": 0,
    "boxanimatetime": 200,
    "enablehscroll": 1,
    "enablevscroll": 1,
    "devicewidth": 0.0,
    "description": "",
    "digest": "",
    "tags": "",
    "style": "",
    "subpatcher_template": "",
    "assistshowspatchername": 0,
    "boxes": [],
    "lines": [],
    "dependency_cache": [],
    "autosave": 0
  }
}

Notes:

  • fileversion: 1 is current across Max 5–9. Never bumped in the wild.
  • appversion is an object, not a string. modernui: 1 is required for Max 8+ devices.
  • classnamespace: "box" for normal patchers and at the device root. Use "dsp.gen" inside gen~ subpatchers, "rnbo" inside RNBO, "dsp.basic" inside poly~ voice patchers.
  • For M4L devices set openinpresentation: 1 AND include a project block (§7).
  • devicewidth 0 = auto-size. Set to a positive integer pixel count for fixed width.
  • dependency_cache: [] is fine for fresh patches.

2. boxes array — per-box schema

Each element is { "box": { ... } }. Required fields on every box:

Key Type Notes
id string Unique within patcher. Convention "obj-1", "obj-2", … One counter per patcher.
maxclass string newobj, message, comment, flonum, number, toggle, button, inlet, outlet, live.dial, live.numbox, live.text, bpatcher, panel, slider, etc.
numinlets integer Must match the underlying class. Wrong values silently mis-wire on load.
numoutlets integer Same.
patching_rect [x,y,w,h] floats Position/size in patching view (the cabling view). Live users never see this.
outlettype array Length must equal numoutlets. Strings: "", "bang", "signal", "int", "float". Omit when numoutlets == 0.

Optional but common:

  • varname — scripting name. Required on live.* UI objects you want to reference by thispatcher, live.banks, or pattr.
  • presentation — 1 to show in presentation mode. See m4l-presentation-layout.
  • presentation_rect — [x,y,w,h] integers when presentation: 1.
  • style — named style; "" is fine.
  • fontname, fontsize, fontface — per-box font override.
  • bgcolor, textcolor, color — RGBA arrays of 4 floats 0–1.
  • hint — tooltip.
  • parameter_enable — 1 for Live-parameter-aware boxes.
  • saved_attribute_attributes.valueof — parameter definition block (see m4l-live-api).
  • prototypename — saved Max prototype.

Box-class examples

newobj — any text-defined Max object. Always uses "text" field:

{ "box": { "id":"obj-1", "maxclass":"newobj", "text":"cycle~ 440",
           "numinlets":2, "numoutlets":1, "outlettype":["signal"],
           "patching_rect":[40.0,40.0,60.0,22.0] } }

message — message box. text is the message contents.

{ "box": { "id":"obj-2", "maxclass":"message", "text":"bang",
           "numinlets":2, "numoutlets":1, "outlettype":[""],
           "patching_rect":[40.0,100.0,40.0,22.0] } }

comment — text label. numoutlets: 0. Multi-line via "linecount": 2 etc.

{ "box": { "id":"obj-3", "maxclass":"comment", "text":"Gain",
           "numinlets":1, "numoutlets":0,
           "patching_rect":[40.0,200.0,80.0,20.0] } }

flonum / number — number boxes:

{ "box": { "id":"obj-4", "maxclass":"flonum",
           "numinlets":1, "numoutlets":2, "outlettype":["float","bang"],
           "patching_rect":[40.0,60.0,50.0,22.0] } }

toggle / button:

{ "box": { "id":"obj-5", "maxclass":"toggle",
           "numinlets":1, "numoutlets":1, "outlettype":["int"],
           "patching_rect":[40.0,40.0,24.0,24.0] } }
{ "box": { "id":"obj-6", "maxclass":"button",
           "numinlets":1, "numoutlets":1, "outlettype":["bang"],
           "patching_rect":[80.0,40.0,24.0,24.0] } }

inlet / outlet — subpatcher I/O. The leftmost (lowest patching_rect[0]) inlet is inlet 0.

{ "box": { "id":"obj-7", "maxclass":"inlet",
           "numinlets":0, "numoutlets":1, "outlettype":[""],
           "patching_rect":[40.0,40.0,30.0,30.0],
           "comment":"" } }

bpatcher — embedded patcher view. Requires name, offset:

{ "box": { "id":"obj-8", "maxclass":"bpatcher",
           "name":"submodule.maxpat", "offset":[0.0,0.0],
           "viewvisibility":1, "varname":"submodule",
           "numinlets":1, "numoutlets":1, "outlettype":[""],
           "patching_rect":[40.0,300.0,200.0,100.0],
           "presentation":1, "presentation_rect":[10,10,200,100] } }

Live UI objects (live.dial, live.numbox, live.slider, live.text, live.toggle, live.button, live.menu, live.tab, live.step, live.grid, live.gain~, live.meter~, live.scope~, live.banks, live.comment, live.drop, live.line) — used in M4L devices. See m4l-live-api for the full parameter inspector block.

Minimal live.dial:

{ "box": { "id":"obj-9", "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
             }
           }
         } }

3. lines array — patch cords

Each line is { "patchline": { ... } }. Required:

{ "patchline": {
    "source":      ["obj-1", 0],
    "destination": ["obj-2", 0]
} }
  • source = [srcId, outletIdx], destination = [dstId, inletIdx]. 0-based indices.
  • Outlet index must be < numoutlets of source; inlet index < numinlets of dest. Mismatch silently drops the cord.

Optional:

  • "order": 0 — when multiple lines start from the same outlet, this controls right-to-left execution order; lower draws first/executes first.
  • "disabled": 1 — visible but inactive.
  • "hidden": 1 — invisible.
  • "midpoints": [x1,y1,x2,y2,...] — manual bend points in patching pixels.

4. parameters (patcher-level, auto-generated)

Max writes a top-level "parameters" map summarizing every parameter in the patcher and subpatchers. Keys are dotted paths ("obj-27" or "obj-1::obj-101"), values are [longname, shortname, flags]:

"parameters": {
  "obj-27": [ "freq", "Freq", 0 ],
  "obj-1::obj-101": [ "subFreq", "Sub Freq", 0 ]
}

Best practice when generating: OMIT this block. Max regenerates it on first save. A stale parameters map that disagrees with boxes is worse than no map.

5. parameterbanks — Push / hardware bank layout

Optional. Each bank holds up to 8 encoder slots:

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

"-" = empty slot. See m4l-live-api § live.banks.

6. dependency_cache and autosave

dependency_cache: [] and autosave: 0 are always safe. Max auto-populates dependency_cache on save with paths to abstractions and externals. Clearing it ([]) is harmless for self-contained patches and routinely done by hand on the forum.

7. project block — MANDATORY for .amxd

Without this block, Max prints:

"a project without a name is like a day without sunshine. fatal."

…and the device refuses to load. Minimum shape:

"project": {
  "version": 1,
  "creationdate": 3793766400,
  "modificationdate": 3793766400,
  "viewrect": [0.0, 0.0, 300.0, 500.0],
  "autoorganize": 1,
  "hideprojectwindow": 1,
  "showdependencies": 1,
  "autolocalize": 0,
  "contents": { "patchers": {} },
  "layout": {},
  "searchpath": {},
  "detailsvisible": 0,
  "amxdtype": 1633771873,
  "readonly": 0,
  "devpathtype": 0,
  "devpath": ".",
  "sortmode": 0,
  "viewmode": 0,
  "includepackages": 0
}
  • creationdate / modificationdate use the Mac classic epoch: seconds since 1904-01-01 UTC. Convert: mac_epoch = unix_epoch + 2_082_844_800.
  • amxdtype is the FOURCC reinterpreted as big-endian uint32:
    • Audio Effect (aaaa): 1633771873
    • Instrument (iiii): 1768515945
    • MIDI Effect (mmmm): 1835887981
  • contents.patchers = {} keeps the device self-contained.

8. Subpatchers

A subpatcher box is a newobj with text "p name" or "patcher name" (or gen~, poly~ name 2) AND an additional "patcher" key whose value is a nested patcher object (same schema as top-level, no outer wrapper):

{ "box": {
    "id":"obj-10", "maxclass":"newobj", "text":"p dsp",
    "numinlets":1, "numoutlets":1, "outlettype":["signal"],
    "patching_rect":[60.0,200.0,40.0,22.0],
    "patcher": {
       "fileversion":1, "appversion":{"major":8,"minor":5,"revision":5,"architecture":"x64","modernui":1},
       "classnamespace":"box",
       "rect":[0,0,640,480], "boxes":[...], "lines":[...]
    }
} }

For gen~ use "classnamespace": "dsp.gen" in the nested patcher. For RNBO, "rnbo". The outer box's numinlets / numoutlets must match the count of inlet / outlet boxes inside.

9. Pitfalls checklist

  1. Duplicate id across boxes → silent merge/drop on load. Single counter per patcher.
  2. Mismatched numinlets/numoutlets → wrong wiring or "patcher connect: inlet out of range".
  3. outlettype length ≠ numoutlets → silent failures.
  4. Off-screen patching_rect → boxes invisible in editor but device still loads (weird debugging).
  5. Float coordinates in presentation_rect → blurry rendering.
  6. UTF-8 BOM, NaN, Infinity, JSON comments, trailing commas → all rejected.
  7. Patchline referencing a non-existent id → cord silently dropped.
  8. Marking infrastructure objects (live.thisdevice, live.observer, live.path, live.object, live.remote~, live.banks) as presentation: 1 → no visual purpose; py2max refuses to do this.
  9. Forgetting varname on live.* UI controls → cannot be addressed by thispatcher, live.banks, or pattr.
  10. .amxd without project block → "a project without a name is like a day without sunshine. fatal." and refusal to load.
  11. Stray control characters (0x00–0x1F except tab/CR/LF) in "text" fields → "Newobj: text could not be parsed" / "error parsing patcher file". Use TextWrangler/BBEdit "Zap Gremlins" to clean.

10. Object-name typos to avoid

  • flonum (UI float number box) ≠ float (object class for float storage).
  • number~ (signal display) ≠ number (UI int box).
  • Tilde objects always include ~: cycle~, *~, +~, dac~, ezdac~, live.gain~, live.meter~, live.scope~, live.remote~, gen~, poly~, mc.gen~, plugin~, plugout~.
  • In Python identifiers (py2max), tilde becomes _tilde (e.g., add_cycle_tilde("cycle~ 440")).

11. Minimum valid .maxpat examples

Audio Effect template — templates/minimal-audio-effect.maxpat:

  • plugin~ → *~ 0.5 → plugout~
  • Includes project block ready for amxd packing

Instrument template — templates/minimal-instrument.maxpat:

  • midiin → midiparse → voice engine → plugout~

MIDI Effect template — templates/minimal-midi-effect.maxpat:

  • midiin → passthrough → midiout

Always start by copying a template and modifying. The templates fix the easy-to-get-wrong fields (project, classnamespace, appversion, openinpresentation, I/O objects) so you only have to add DSP/MIDI logic and UI.

12. Recommended emit pattern (LLM authoring)

  1. Allocate id_counter = 1, walk your conceptual graph, emit each box with "obj-${id_counter++}".
  2. Look up numinlets / numoutlets per newobj text. If unknown, default to 2/1/["signal"] for tilde objects, 1/1/[""] for non-tilde. Verify against Max docs.
  3. Place boxes in a column at x=40 incremented by y=50 per box for the patching view (anywhere not overlapping).
  4. For UI boxes (live.dial etc.), set "presentation": 1, integer presentation_rect, and the parameter block (see m4l-live-api).
  5. Emit patchlines after all boxes; verify each id and index.
  6. Include project block if packaging as .amxd.
  7. Open in Max once, save from Max — this normalizes dependency_cache, ordering, and catches "Newobj: text could not be parsed" before Live ever sees the file.

For non-trivial devices use py2max (see m4l-py2max-tooling) instead of writing JSON by hand. It validates inlet/outlet counts via a MaxRef DB of 1157 objects.