Add native Max for Live (.amxd) device support

[chrishyoroklee]

Summary

Adds native Max for Live (.amxd) device support to MaxPyLang — save and load patches as Ableton Live devices directly from Python.

Supported device types

device_type	Input	Output	Ableton track
"instrument"	notein	plugout~	MIDI track
"audio_effect"	plugin~	plugout~	Audio track
"midi_effect"	midiin → midiparse	midiformat → midiout	MIDI track

Usage

Instrument (MIDI → audio):

import maxpylang as mp

patch = mp.MaxPatch()
notein = patch.place("notein")[0]
mtof = patch.place("mtof")[0]
osc = patch.place("cycle~")[0]
clip = patch.place("clip~ -1. 1.")[0]
plugout = patch.place("plugout~")[0]

patch.connect(
    [notein.outs[0], mtof.ins[0]],
    [mtof.outs[0], osc.ins[0]],
    [osc.outs[0], clip.ins[0]],
    [clip.outs[0], plugout.ins[0]],
    [clip.outs[0], plugout.ins[1]],
)

patch.save("my_synth.amxd", device_type="instrument")

Audio effect (audio → audio):

patch = mp.MaxPatch()
plugin = patch.place("plugin~")[0]
filt = patch.place("lores~ 2000 0.5")[0]
clip = patch.place("clip~ -1. 1.")[0]
plugout = patch.place("plugout~")[0]

patch.connect(
    [plugin.outs[0], filt.ins[0]],
    [filt.outs[0], clip.ins[0]],
    [clip.outs[0], plugout.ins[0]],
    [clip.outs[0], plugout.ins[1]],
)

patch.save("my_filter.amxd", device_type="audio_effect")

Standalone functions for advanced use:

from maxpylang import save_amxd, load_amxd

json_dict = patch.get_json()
save_amxd(json_dict, "device.amxd", device_type="instrument")

json_dict = load_amxd("device.amxd")

Other fixes

• Fix notein args: mark port-channel and channel as optional so notein can be placed without arguments
• Harden load_amxd: use rstrip for multiple trailing nulls, compare chunk tags as raw bytes, include filename in error messages

CI

• Runs 5 standalone examples in CI: hello_world, m4l_instrument, m4l_audio_effect, attributes, random_pitch_generator
• Verifies each example produces its expected output file
• Runs 81 pytest tests covering amxd binary format, round-trips, extension handling, M4L I/O objects, and backward compatibility

Test plan

• patch.save("test.amxd", device_type="instrument") produces a valid .amxd file openable in Ableton
• load_amxd("test.amxd") round-trips correctly
• patch.place("notein")[0] works without errors
• Saving .amxd without device_type raises ValueError
• Existing .maxpat save behavior is unchanged

[santolucito]

Can we add something in CI that tests this?

[santolucito]

like maybe we shoudl at least just run maxpy on the example folder in ci to make sure we dont break these at least from a maxpy pass. i dont know that there is any good way to have full integration tests

[chrishyoroklee]

@santolucito
I had Claude set these up in CI:

• 5 standalone examples run in CI (hello_world, m4l_instrument, m4l_audio_effect, attributes, random_pitch_generator)
• 81 pytest tests (amxd + backward compat)
• Output file verification for each example