SuperAPI AI Directory

m4l-amxd-conversion

Coding & development

View repository

Updated 10-16 03:41

About this skill

.amxd Container Format and Conversion

.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)

  1. Open the .maxpat (or New From Template → Max Audio Effect for a fresh device).
  2. File → Save As… → pick Save 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).
  3. 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 needs x86_64, Windows needs mxe64. Missing slice → "could not load due to incorrect architecture".
  • Develop unfrozen, distribute frozen. Keep unfrozen source in git; frozen .amxd is 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 .amxd onto 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 .amxd on 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 .maxpat to .amxd. It won't load.
  • ALWAYS include the project block when packing as .amxd.
  • ALWAYS match header FOURCC and project.amxdtype.
  • PREFER the canonical mx@c form 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.