.amxd files are NOT just renamed .maxpat files. They are an IFF-style binary container with a 36-byte mixed-endian header, the patcher JSON NUL-terminated, then a dlst/dire dependency trailer.
The format is undocumented by Cycling '74; everything here is reverse-engineered from Max-exported devices, the shakfu/py2max Python library, and Ableton's official maxdevtools/maxdiff/amxd_textconv.py parser.
1. Byte layout (Max-native canonical form)
offset size endian value meaning
0 4 - "ampf" magic
4 4 LE u32 4 format version
8 4 - "aaaa" / "iiii" / "mmmm" device type FOURCC
12 4 - "ptch" top-level chunk id
16 4 LE u32 file_size - 20 ptch payload size
20 4 - "mx@c" sub-block id
24 4 BE u32 16 constant (JSON offset within mx@c)
28 4 BE u32 0 flags
32 4 BE u32 json_size + 16 mx@c content size
36 N+1 - <utf-8 json>\x00 JSON, NUL-terminated
36+N+1 - - <IFF-style dlst/dire trailer>
Critical subtleties:
- Endianness is mixed. Offset 4 and offset 16 are little-endian. Offset 24, 28, 32 and ALL trailer chunk sizes are big-endian. Reversing either silently breaks loading.
- Bytes 8–11 are the device-type FOURCC, not padding. Older community docs (incl. an initial py2max issue #9 draft) said padding — that's wrong.
- The JSON is raw UTF-8 with a single trailing NUL byte. No base64, no compression, no escaping beyond standard JSON.
2. Device-type FOURCCs
| Tag | Device | Hex bytes | amxdtype BE u32 |
|---|---|---|---|
aaaa |
Audio Effect Device | 61 61 61 61 |
1633771873 |
iiii |
Instrument Device | 69 69 69 69 |
1768515945 |
mmmm |
MIDI Effect Device | 6d 6d 6d 6d |
1835887981 |
nagg |
MIDI Tool Generator (Live 12) | 6e 61 67 67 |
1851875687 |
natt |
MIDI Tool Transformation (Live 12) | 6e 61 74 74 |
1851878516 |
ciph |
Encrypted/protected device — opaque body | - | n/a |
Rule: the header FOURCC at offset 8 MUST match the project.amxdtype field inside the JSON (see m4l-maxpat-format §7). If they disagree, behavior is undefined.
3. The IFF trailer
After the JSON's NUL byte, no alignment padding:
dlst (4 + BE u32 size + payload)
dire (4 + BE u32 size + per-dependency record)
type -> "JSON"
fnam -> patcher filename, NUL-terminated, padded to 4-byte boundary
sz32 -> BE u32 — JSON byte count including the NUL
of32 -> BE u32 — 16 (offset of JSON inside the mx@c block)
vers -> BE u32 — 0
flag -> BE u32 — 17
mdat -> BE u32 — modification time in Mac epoch (1904-01-01 UTC)
For frozen devices, dlst contains multiple dire entries — one per embedded dependency (subpatcher, audio file, JS file, image, external). Each entry's of32/sz32 slices its bytes out of the mx@c body.
4. The simpler "three-chunk" form
Several community packers (MaxPyLang, taylorbrook/MAX-MSP_CC_Framework, whistlegraph/aesthetic-computer) write a simpler form that LOADS in Live but is NOT round-trip-stable against Max:
ampf (4 bytes, payload = device type FOURCC, LE u32 size = 4)
meta (4 bytes, empty/4-byte zero payload)
ptch (LE u32 size, raw JSON + trailing NUL)
Max will rewrite this into the canonical mx@c form on next save. Acceptable for one-shot device generation; not acceptable if you want diffable, Max-stable files.
5. Conversion paths
a. Max GUI (interactive)
- Open the
.maxpat(orNew From Template → Max Audio Effectfor a fresh device). File → Save As…→ pickSave As Audio Effect Device/Save As Instrument Device/Save As MIDI Effect Device(the exact wording shifts across Max 7/8/9; always in the File menu).- Max wraps the patcher in the correct FOURCC and writes the trailer.
Default save location: the User Library subfolder for the device type. Saving elsewhere risks breaking path references in Live Sets that use the device.
b. Headless / programmatic
The reference implementation is shakfu/py2max's py2max.m4l:
from py2max.m4l import write_amxd, ensure_amxd_project_block
# patcher_dict is your loaded/built .maxpat dictionary
ensure_amxd_project_block(patcher_dict, device_type="audio_effect")
write_amxd("MyDevice.amxd", patcher_dict, device_type="audio_effect")
A standalone packer (works without py2max) lives at scripts/pack_amxd.py in this skill — it implements the canonical 36-byte mx@c form. Usage:
python3 scripts/pack_amxd.py audio_effect input.maxpat output.amxd
c. Extraction (.amxd → .maxpat)
import struct, json
def unpack_amxd(path):
data = open(path, "rb").read()
assert data[0:4] == b"ampf"
version, = struct.unpack("<I", data[4:8])
device_tag = data[8:12] # "aaaa" / "iiii" / "mmmm"
assert data[12:16] == b"ptch"
ptch_size, = struct.unpack("<I", data[16:20])
body = data[20:20+ptch_size]
if body[:4] == b"mx@c":
# canonical form: skip 16-byte mx@c preamble, then read NUL-terminated JSON
json_bytes = body[16:].split(b"\x00", 1)[0]
else:
# three-chunk form: ptch payload is raw JSON + NUL
json_bytes = body.split(b"\x00", 1)[0]
return device_tag.decode(), json.loads(json_bytes.decode("utf-8"))
tag, patcher = unpack_amxd("MyDevice.amxd")
open("MyDevice.maxpat", "w").write(json.dumps(patcher, indent=2))
Note: renaming .amxd to .maxpat does NOT work — the binary header confuses Max's parser. You must strip the header chunks.
For frozen devices with multiple dependencies, use Ableton's official tool: python3 maxdiff/amxd_textconv.py path/to/device.amxd from https://github.com/Ableton/maxdevtools.
6. Freeze / unfreeze
The Freeze Device action (snowflake icon in Max patcher toolbar) embeds every dependency the device references into the .amxd. Mechanically, each dependency becomes a dire entry in the trailer with its bytes pulled from the mx@c body.
When to freeze: before distribution. Always. Otherwise users on other machines won't have your abstractions, sample files, JS files, or third-party externals.
Caveats:
- Some packages (e.g.,
bach) don't auto-bundle reliably — third-party externals may still be missing on user machines. - Externals must include all required architectures: macOS Apple Silicon needs
arm64, Intel macOS needsx86_64, Windows needsmxe64. Missing slice → "could not load due to incorrect architecture". - Develop unfrozen, distribute frozen. Keep unfrozen source in git; frozen
.amxdis a build artifact. - Editing a frozen device from Live makes a copy into the User Library — your edits land somewhere different from the source file.
7. User Library locations (where Live discovers .amxd)
macOS:
~/Music/Ableton/User Library/Presets/Audio Effects/Max Audio Effect/
~/Music/Ableton/User Library/Presets/Instruments/Max Instrument/
~/Music/Ableton/User Library/Presets/MIDI Effects/Max MIDI Effect/
~/Music/Ableton/User Library/Presets/MIDI Tools/Max MIDI Tool/ (Live 12+)
Windows:
%USERPROFILE%\Documents\Ableton\User Library\Presets\Audio Effects\Max Audio Effect\
%USERPROFILE%\Documents\Ableton\User Library\Presets\Instruments\Max Instrument\
%USERPROFILE%\Documents\Ableton\User Library\Presets\MIDI Effects\Max MIDI Effect\
%USERPROFILE%\Documents\Ableton\User Library\Presets\MIDI Tools\Max MIDI Tool\
Live scans these on launch and on file changes. The User Library root is configurable in Live's Preferences → Library.
Drop-folder mismatch: a device with FOURCC aaaa placed in the Instruments folder will still load when dragged onto a track, but won't appear in the Audio Effects browser category.
8. Common load failures
| Symptom in Live | Likely cause |
|---|---|
| "Could not open this device" | Malformed amxd container or malformed JSON |
| "a project without a name is like a day…" | Missing project block in patcher JSON (m4l-maxpat-format §7) |
| Device loads but does nothing | Wrong I/O objects for the type (e.g., plugin~ in a MIDI effect) |
| Device shows blank UI | Missing openinpresentation: 1, no boxes with presentation: 1 |
| Device loads but knobs aren't mappable | parameter_enable missing or wrong Parameter Visibility |
| Device works in Max but not in Live | Patcher requires standalone Max objects unavailable in M4L runtime |
| Architecture errors on Apple Silicon | Bundled externals are x86_64-only; delete externals/ and use system universal builds |
9. Loading mechanics
- Drag the
.amxdonto a track in Live to load. Double-click does NOT work — it opens Max which won't load it as a device. Right-click → "Open in Ableton Live" also does not work in some Live versions. - Hot-reload: saving from Max updates all loaded instances of that device in the current Live Set automatically. Changing the
.amxdon disk while Live is open without going through Max — Live will NOT pick up the change unless the device is re-dragged.
10. Right-click → Open Max Window
To see errors from a loaded device: right-click the device's title bar in Live → Open Max Window. This is the primary debugging surface. See m4l-debugging for the full error catalog.
11. Quick rules of thumb for the LLM
- NEVER rename
.maxpatto.amxd. It won't load. - ALWAYS include the
projectblock when packing as.amxd. - ALWAYS match header FOURCC and
project.amxdtype. - PREFER the canonical
mx@cform over the three-chunk form when round-trip stability matters. - USE py2max for non-trivial generation — it gets the byte order and NUL termination right (see
m4l-py2max-tooling). - TEST by dragging the result onto a track in Live, then opening the Max Window for errors.