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: 1is current across Max 5–9. Never bumped in the wild.appversionis an object, not a string.modernui: 1is required for Max 8+ devices.classnamespace: "box"for normal patchers and at the device root. Use"dsp.gen"insidegen~subpatchers,"rnbo"inside RNBO,"dsp.basic"insidepoly~voice patchers.- For M4L devices set
openinpresentation: 1AND include aprojectblock (§7). devicewidth0 = 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 onlive.*UI objects you want to reference bythispatcher,live.banks, orpattr.presentation—1to show in presentation mode. Seem4l-presentation-layout.presentation_rect—[x,y,w,h]integers whenpresentation: 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—1for Live-parameter-aware boxes.saved_attribute_attributes.valueof— parameter definition block (seem4l-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
< numoutletsof source; inlet index< numinletsof 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/modificationdateuse the Mac classic epoch: seconds since 1904-01-01 UTC. Convert:mac_epoch = unix_epoch + 2_082_844_800.amxdtypeis the FOURCC reinterpreted as big-endian uint32:- Audio Effect (
aaaa):1633771873 - Instrument (
iiii):1768515945 - MIDI Effect (
mmmm):1835887981
- Audio Effect (
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
- Duplicate
idacross boxes → silent merge/drop on load. Single counter per patcher. - Mismatched
numinlets/numoutlets→ wrong wiring or "patcher connect: inlet out of range". outlettypelength ≠numoutlets→ silent failures.- Off-screen
patching_rect→ boxes invisible in editor but device still loads (weird debugging). - Float coordinates in
presentation_rect→ blurry rendering. - UTF-8 BOM, NaN, Infinity, JSON comments, trailing commas → all rejected.
- Patchline referencing a non-existent
id→ cord silently dropped. - Marking infrastructure objects (
live.thisdevice,live.observer,live.path,live.object,live.remote~,live.banks) aspresentation: 1→ no visual purpose; py2max refuses to do this. - Forgetting
varnameonlive.*UI controls → cannot be addressed bythispatcher,live.banks, orpattr. .amxdwithoutprojectblock →"a project without a name is like a day without sunshine. fatal."and refusal to load.- 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
projectblock 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)
- Allocate
id_counter = 1, walk your conceptual graph, emit each box with"obj-${id_counter++}". - Look up
numinlets/numoutletspernewobjtext. If unknown, default to2/1/["signal"]for tilde objects,1/1/[""]for non-tilde. Verify against Max docs. - Place boxes in a column at x=40 incremented by y=50 per box for the patching view (anywhere not overlapping).
- For UI boxes (
live.dialetc.), set"presentation": 1, integerpresentation_rect, and the parameter block (seem4l-live-api). - Emit patchlines after all boxes; verify each id and index.
- Include
projectblock if packaging as.amxd. - 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.