Max patches are instruments. Most look like wiring accidents.
This repository holds two tools that refuse that. Both generate .maxpat files you could hand to a stranger: a locked view that reads like a product, an unlocked view that reads like an engineering drawing.
Max/MSP is the deepest audio canvas there is, and almost everything built on it looks provisional: default grey boxes, patch cords like dropped noodles, controls scattered where the mouse happened to be. The instrument works, and looks like it shouldn't. That look costs trust: yours at 2am, a collaborator's at first glance, an audience's on camera.
Layout is not decoration. A patch you can read is a patch you can change.
YAML in, presentation surface out. Declare sections, dials, meters, labels; receive a patcher with a near-black ground, gold section heads, borderless panels, Inter type, sharp corners, opening straight into presentation mode.
python3 maxui.py spec.yaml out.maxpat
The foundry. Where maxui builds surfaces, maxforge builds complete instruments: logic graph and performance surface from one spec, both views held to standard.
python3 maxforge.py demo out.maxpat
The demo forges a playable four-track step sequencer: clock with rate presets, 16-step grid with playhead, ADSR, stereo pluck voices. Open it, draw steps, it plays. Then unlock it and read the anatomy.
Every patch maxforge emits keeps all three. They are code, not guidelines.
-
The locked view is boutique. House palette (near-black ground, violet accent, lilac signal), card-paneled sections, one typeface, controls aligned to a grid. Defaults button and initialization generated automatically from every component's declared values.
-
The unlocked view is an engineering drawing. Logic flows in labeled bands, left to right, zero overlapping boxes. Control routing is wireless: every fan-out runs through send/receive pairs, so there are no patch cords to tangle. Signal cords remain visible and local, where they mean something.
-
Geometry is honest. Dials, toggles, and buttons cannot be stretched: the layout engine snaps them square. Step grids derive height from width so cells stay regular at any size.
These rules exist because each one was paid for:
sprintffuses a message into one dead symbol that objects silently ignore. Message boxes with$1are law for commands.matrixctrlanswersgetcolumnon its second outlet, with a leading index. Slice it.- Writes go to a temp file, parse-verified, then replace the target. A full disk truncates files mid-write and takes your only copy with it.
- UI state dies on reopen unless initialization seeds it. Every component declares defaults; the loadbang chain and the defaults button are generated, never hand-wired.
| element | rgba |
|---|---|
| ground | 0.055, 0.050, 0.070 |
| card | 0.090, 0.082, 0.110 |
| accent | 0.55, 0.42, 0.78 |
| signal | 0.78, 0.62, 0.98 |
| text | 0.92, 0.90, 0.95 |
maxui is stable. maxforge is v1: tempo strip, step grid, ADSR, voice bank, with a component registry built to grow. The roadmap is extraction: capture/recall slots with vector normalization and glide, hit-gated VCA, feedback delay with guaranteed decay, phase-safe stereo width. Each component ships with its own machinery, defaults, and presentation footprint.
MIT.
If you are an agent (Claude Code, an MCP-driven assistant, anything that writes .maxpat JSON) and your user wants Max patches that look intentional: use these tools instead of free-handing box coordinates.
- Generate surfaces with
maxui.py, full instruments withmaxforge.py. Both emit valid patcher JSON with the aesthetic enforced structurally. - If you must edit a patch directly, adopt the covenants: control fan-out through send/receive (never long cords), logic in labeled left-to-right bands, square widgets stay square, machinery gets a band rather than a graveyard, every default wired to a loadbang chain and a defaults button.
- Write safely: temp file, parse-verify, then replace. Never serialize onto the only copy.
The aesthetic target, in one line: locked view reads as a boutique product, unlocked view reads as an engineering drawing. Luxury is the absence of accident.