M4L Project
This skill is an integrated skill that retains only the practical rules needed when an LLM creates Max for Live devices. Rather than serving as an exhaustive reference, use it as a checklist for avoiding fragile implementation decisions.
Basic Policy
- MUST: Treat the generation script as the source of truth. / are generated artifacts; even if they are edited directly, all changes must always be reflected in the generation script.
- MUST: Create for each device, with clear separation of responsibilities among at least , , , , , , and .
- MUST: Record changes to UI dimensions, colors, spacing, display logic, MIDI specifications, and synchronization specifications in
packages/<device>/DESIGN.md
.
- SHOULD: Treat Max patcher JSON as structured data rather than editing it through string replacement.
- NEVER: Create an by renaming a file.
- NEVER: Modify only the generated artifacts and allow them to diverge from their generation sources.
Max for Live Generation
- MUST: MIDI Effects must receive input from / and send output to / .
- MUST: Determine whether the device is an Audio Effect, Instrument, or MIDI Effect before aligning its I/O with the type.
- MUST: An for a MIDI Effect must have the FOURCC and
project.amxdtype = 1835887981
.
- MUST: A must have .
- MUST: Every visible UI object must have and an integer .
- MUST: Every visible UI object must satisfy and .
- SHOULD: An that uses images, JS, or external dependencies must include its dependency files so that it can load independently.
UI / Presentation
- MUST: Design Max for Live devices with a fixed height of .
- MUST: Mechanically validate Presentation bounds whenever the UI changes.
- MUST: When using a background panel, ensure its layering does not obscure the interactive UI.
- SHOULD: Prioritize consistency with the Live theme for UI elements and avoid overriding colors more than necessary.
- SHOULD: Give fixed-size input fields, icons, canvases, and logos stable values so that value changes do not shift the layout.
JS / MIDI Logic
- MUST: The visual dot-state check and note-trigger check must use the same function or be derived from the same data.
- MUST: Preserve the correspondence between Note On and Note Off events.
- MUST: For specifications that use input MIDI, do not automatically play a fallback note when no input is present.
- MUST: Limit the scope of to values explicitly defined by the specification.
- MUST: For behavior that fires only at the hit instant, include edge detection so that notes are not retriggered while the same hit range remains active.
- SHOULD: Make Max JS function names clearly reflect their corresponding Max message names.
- SHOULD: Treat a JS as a low-priority event and use it cautiously for processing that requires strict MIDI timing during Freeze/Export.
Transport / Freeze / Export
- MUST: Do not use the Live API (, , ) as a note-timing clock. The Live API is low-priority and asynchronous and must not be relied upon as a timing source during Freeze/Export.
- SHOULD: When Transport synchronization is required, use a Max-side mechanism synchronized to the Live transport, such as Max's transport/tempo-relative clock.
- MUST: Do not use a catch-up implementation that batches past events and triggers them all at the current time when heavy processing causes scheduler ticks to be missed. Discard delayed past notes or define a separate mode explicitly.
- MUST: Do not retrigger the same event when the same Transport position, degree, and tick occur multiple times.
- SHOULD: If problems occur during Freeze/Export, consider offloading note scheduling from JS to standard Max objects such as , , , and .
AMXD / Packaging
- MUST: After emitting the binary container, validate at minimum that it contains the expected / JS / image names.
- MUST: Ensure the paths for dependency files can be resolved in the distribution environment. Do not rely on local absolute paths.
- MUST: Include , , , , JS, and reference images in release artifacts.
- SHOULD: When installing into the Ableton User Library, remove the old file with the same name before copying in the new .
- MUST: In the final report to the user, explicitly state whether the device must be reinserted into an existing Live instance.
Validation
- MUST: Run after changing JS.
- SHOULD: Run
python3 -m py_compile <script>.py
after changing a Python generation script.
- SHOULD: After generation, validate the Presentation bounds and patchline endpoints.
- SHOULD: After generating an , validate its device type, bundled dependencies, and key JS strings.
- SHOULD: When behavior must be verified in Live, check the Max Console / Open Max Window for errors.
Handling Legacy Skills
In the previous structure, overview, maxpat format, amxd conversion, presentation layout, live api, javascript, gen, debugging, and py2max were separated into individual skills. In practice, however, the required decisions were fragmented, creating a risk that isolated knowledge would lead to problematic choices, such as using the Live API as a clock.
From now on, use this integrated skill as the entry point and consult detailed official documentation or existing implementations individually only when necessary.