Everything MESA does, and how to drive it.

Getting Started

Your first patch

The window is organized in rows: the reactive terrain display and preset/shader switchers on top; a row of knob panels (Oscillator, Filter, Envelope, Pitch·Sub); a row of routing/FX panels (Mod Matrix, FX Sends, Tape FX, Layer); and a row for the wider chip-based panels (Vision, VFX, Arpeggiator). On narrow windows these stack vertically instead.

Vision Panel

Tune how MESA sees

Vision is the bridge between the picture and the waveform. Five controls, all live (re-importing the shader whenever you move one), all MIDI-learnable.

Control	What it does
Scan Y	Which horizontal slice of the rendered image becomes the waveform — drag 0 (top) to 1 (bottom). Different rows through the same shader are completely different timbres.
Channel	How R/G/B combine into the luminance sample: RGB (standard weighting), R, G, B only, R−B (chroma axis), or Equal weight.
Curve	Nonlinear reshaping applied after luminance extraction: Linear, Gamma (√, expands shadows), S-curve (soft-knee), Fold (wavefold at the midpoint), Rectify (full-wave — doubles the fundamental), Invert.
Time	How the 64 frame indices map onto the shader's time uniform: Linear, Exponential, Sinusoidal, S-curve, Reverse, Bounce (ping-pong).
Energy ↑	Toggle. When on, the shader's energy uniform sweeps 0→1 across the 64 frames instead of sitting fixed at 0.5 — shaders that react to energy produce a morphing, evolving wavetable.

Hide the visuals to save GPU

The eye button in the terrain's corner pauses the on-screen render. It's purely cosmetic — the wavetable is extracted on a separate offline pass, so the sound is completely unchanged — which makes it a free performance lever, especially for the AUv3 sharing a GPU with a busy DAW. As an AUv3 it also pauses automatically whenever the host hides the plug-in's editor (a real saving in AUM, Loopy Pro or Logic, where an instance stays loaded with its window closed); the standalone app pauses when it isn't the frontmost app. A decaying reverb or delay tail no longer quietly loads a core either — subnormal floats are flushed on the audio thread.

VFX Chain

26 modifiers, stacked

A modifier chain sits between the raw shader and the final image — and since the image is the sound source, every modifier is also an audio effect. Five of them (filmLook, bloom, rgbSplit, datamosh, mask) trace automatically out of a .vkograph graph; all 26 can be added natively from the VFX panel's picker. Each node has a drag-adjustable primary parameter and its own wet/dry blend.

Sound Engine

Filter · ZDF

A zero-delay-feedback state-variable low-pass, one per voice.

Control	Range	Notes
Cutoff	20 Hz – 20 kHz
Resonance	0–1	Self-oscillates at the top of the range.
Drive	0–1	A single knob that drives two stages at once: per-voice tanh saturation ahead of the filter, and the post-mix waveshaper stage in the FX chain.

Modulation

Mod matrix

Two LFOs are hard-routed by default — LFO 1 → Morph, LFO 2 → Cutoff — with a drag bar that shows the live modulation swing and sets the depth. A third slot is fully free-assign.

Slot	Source	Destination	Amount
1	LFO 1 (fixed)	Morph (fixed)	0–100%
2	LFO 2 (fixed)	Cutoff (fixed)	0–100%
3	LFO 1 / LFO 2 / Wheel / Velo — tap to cycle	Morph / Cutoff / Reso / Level / Pitch — tap to cycle	−100% to +100% (bipolar)

Mod-wheel and velocity are also wired directly into the DSP layer as modulation sources. Every mod-matrix value is a real host-automatable AU parameter.

Performance

Performance FX

A Kaoss-style XY pad on the master bus — one effect at a time, live only while a finger is down. It's a stab, not a setting. Off by default, and Off is a real bypass in the DSP (the section returns before touching a sample), so an unused Perf FX costs nothing.

Effect	X axis	Y axis
FILTER	Cutoff, LP ‹ › HP	Resonance
STUTTER	Slice length	Decay
CRUSH	Sample-rate crush	Bit depth
GATE	Rate	Depth
DELAY	Time	Feedback
SPACE	Size	Amount

Draw a motion path

Arm the pencil and paint cells onto the pad. The cells are the path, in the order you drew them, and the DSP walks them one per tempo division (1/4, 1/8, 1/16, 1/32) while the effect is engaged — so a drawn squiggle plays itself, in time. Under Hold it runs hands-free. The path (and the effect choice, and the enable state) saves with the patch; engaging and the raw X/Y are momentary.

Fullscreen

The same pad edge to edge, for a bigger target during a set.

Output Stage

Global volume & master limiter

Global Volume, in the top bar, sits downstream of the entire patch — every knob, the whole FX chain, both layers — so switching presets never changes how loud MESA is, and a preset save/load or a randomizer roll never touches it. It's a real MIDI-learnable, host-automatable AU parameter (masterVolume), separate from the patch's own Gain knob.

Behind it, a master limiter catches peaks before they reach the output. A synth patch can legitimately run hot — 8-voice unison plus sub plus drive plus resonance, times up to 16 held voices — and in the standalone app the engine feeds the output device directly, so anything past 0dB hard-clips at the DAC. The limiter is peak-detecting with instant attack and a smooth ~150ms release: gain reduction drops immediately to whatever the loudest sample needs, then recovers without ducking the whole patch on a single transient. It is deliberately not a compressor — nothing happens at all below the ceiling, so every existing preset still sounds exactly as it did.

The LIM meter next to Global Volume lights up only while the limiter is actively doing work, so you can see when a patch is running hot instead of guessing.

Motion

Motion — OFF / ARP / SEQ

One selector at the top of the SEQUENCER panel decides what drives the voices, and the three are mutually exclusive on purpose. An arpeggiator is a sequencer whose pattern comes from the notes you're holding — running both would be two generators fighting over the same sixteen voices with no musical relationship between them. So they share one clock, one rate and one swing, and only one plays at a time.

Source	What plays	What the keys do
OFF	Nothing generated.	Play straight through.
ARP	The notes you hold, cycled.	They are the pattern.
SEQ	The step grid.	They transpose the pattern — see below.

The clock comes from the DAW's transport in the plug-in, Ableton Link in the standalone while it's driving, and MESA's own tempo otherwise — in that order.

The arpeggiator

Pick ARP and the panel opens up under the selector — the same panel in the plug-in and the app, laid out like the step grid: rows of chips you hit at a glance rather than a line of cycling pills. It's driven from one shared set of values that MESA hands to whichever arp the host owns — the DSP engine's in the plug-in (clocked to the DAW's beat position), a free-running one in the standalone — so the two behave identically, synced or not.

Control	What it does
Order	Eight of them. Up · Down · Up-Down · Down-Up walk pitch order; Random picks one a step; As-Played follows the order you pressed the keys, not their pitch; Chord fires every held note together on the grid; Converge goes outside-in — lowest, highest, next lowest, and so on.
Rate	1/4 · 1/8 · 1/8T · 1/16 · 1/16T · 1/32.
Octaves + direction	1–4 octaves of range, and whether the stack is walked up ↑, down ↓ or alternating ↕ above and below.
Gate	How much of its step each note holds — spiky staccato through to legato that runs into the next step.
Swing	Pushes the off-steps late, the same feel as the sequencer's swing.
Ratchet	1 (off) to 4 — retriggers the note that many times inside a single step for a roll.
Accent	Off, or every 2nd / 3rd / 4th step at full velocity with the rest sat back — what turns a flat run into a pattern.
Hold	Latches the held notes so the arp keeps running with your hands off. In the plug-in there's no keyboard, so this is how you keep a chord arpeggiating.

In the standalone, when Ableton Link is enabled the free-running rate loses its meaning against a shared beat, so a LINK chip appears below the panel — tap it to cycle which note division the arp steps at on the session grid.

MIDI

Recording MESA into a DAW

MESA is an instrument that also emits MIDI, on a port named MESA Notes, everything on channel 1. That name only shows up in hosts that list plug-in MIDI ports — AUM and apeMatrix put it in the routing matrix. Logic never shows it: there you pick the track MESA is on, so don't go hunting a menu for "MESA Notes".

NOTES OUT

The piano-keys button in the status bar arms the mirror. It sends everything MESA plays that isn't already MIDI — the arpeggiator's pattern, the step sequencer's line, and the terrain ribbon — so a DAW track can capture it as editable MIDI. Notes arriving from the host are never echoed back; the DAW already has those. Filled when armed; a slash badge means it's armed but nothing is reading MESA's port yet, which is the quickest sanity check that the wire is live. Plug-in only — the standalone isn't inside a DAW.

Play it, or record it — two different jobs

People trip over this in AUM especially: wiring MESA to another synth so you can hear it is not the same as capturing the MIDI. The first needs nothing extra; the second needs a recorder.

The one rule, everywhere

A track or a recorder captures what arrives at its input. MESA's own keyboard, ribbon and sequencer sit downstream of that — they talk straight to the engine inside the plug-in — so nothing records them onto MESA's own track by itself, in any host. What you do instead is always the same shape: point something else at MESA's output, and record that. Only the menu names change.

Or skip the routing: export the pattern

No host reads an instrument's MIDI onto its own track by itself, and the routing that does it is several menus deep. A .mid file sidesteps all of it. Drag a pattern slot straight onto a timeline or into Finder — any slot, without switching to it first. The file carries tempo, swing, ties and slides exactly as the sequencer plays them, and the bar runs out to full length so a one-note pattern still drops in as a correctly-sized region.

Then mute the internal pattern

Once the recorded region is back on MESA's own track, the region and the internal sequencer would both fire every note. The grid button next to SEQ stops the pattern playing while its clock keeps advancing — the playhead stays put and re-enabling lands back in phase — and nothing reaches the MIDI mirror either. MESA becomes a plain synth the region drives. It's MIDI-learnable, so a controller can flip it mid-set.

Logic Pro on Mac, end to end

The workflow worth learning: build a line on MESA's sequencer, capture it as a real MIDI region, then hand playback back to MESA and treat it like anything else in the arrangement. Apple calls the routing Internal MIDI In, documented as capturing "the MIDI output of MIDI effect or software instrument plug-ins."

1. Build the line on MESA's step sequencer on track 1. The transport is Logic's — MESA follows it.
2. Arm NOTES OUT. The slash badge clears once a track is actually reading MESA.
3. New software-instrument track; set its input to MESA's track via Internal MIDI In.
4. Record-arm it and roll. What lands is MESA's line as editable MIDI.
5. Drag the region onto MESA's own track, then mute the internal pattern so the two don't double.

Or skip steps 2–4 entirely: export the pattern as a .mid and drag it from Finder.

In iOS hosts

Host	How
AUM	Open the MIDI routing matrix — MESA appears as a source. AUM doesn't record MIDI itself, so wire it to a MIDI-recorder AUv3 or to whatever you want MESA to drive.
Loopy Pro	Load MESA as an audio AUv3 first, then in the mixer tap + → Add MIDI. That channel captures the plug-in's MIDI output and records into a clip.
Drambo	Records AUv3 MIDI output natively (2.20+). Route MESA's MIDI out to a recorder module.
apeMatrix	Same idea as AUM — MESA is a node with a MIDI output; patch it wherever.
Logic Pro for iPad	Apple documents "Record MIDI plug-in output" — same concept as the Mac's Internal MIDI In.

One Tap

Randomizer

The dice button builds an entire new patch in one tap — not knob noise, a designed sound. Each roll picks a character first (pad, bass, lead, pluck, drone, texture) and shapes everything around it: oscillator and filter ranges, envelope shape, which mod-matrix slots get used, FX send levels, palette, Vision settings, and the VFX chain. It always picks a shader you're not already using on either layer, and every roll gets its own generated name.

Rolls also budget their own GPU cost. Some VFX modifiers are far more expensive than others — a blur or bloom re-evaluates the entire underlying shader per tap, so stacking a few of the heaviest together can bog down real-time rendering on a phone or tablet, especially inside a host running its own DSP load alongside MESA. The randomizer weighs each modifier's cost and keeps every roll's chain under a budget, so it can build genuinely varied patches without ever assembling a combination heavy enough to hurt performance.

Don't like what came up? Roll again — nothing is committed until you save it. Like it? Save it like any other patch and it joins your User folder.

MIDI

MIDI Learn

Long-press (or right-click on Mac) almost any control to bind an incoming CC to it. Bindings persist across sessions.

Not mapping a controller? The Settings panel has a MIDI Learn switch that turns the long-press / right-click menu off entirely, so that gesture stops competing with a knob's drag or a button's tap. Anything you've already bound keeps working — the switch only hides the authoring menu.

What's learnable

• All 21 knob-backed parameters: Gain, Morph, Cutoff, Resonance, Unison, Detune, Drive, Delay, Reverb, Layer Blend, Tape, Flutter, Lo-fi, Attack, Decay, Sustain, Release, Sub, Glide, Pitch Env Amount, Pitch Env Decay.
• All three mod-matrix slot amounts (not the slot-3 source/dest chips — those are left un-learnable on purpose, so a sweeping CC can't reroute the matrix mid-performance).
• The Tape Stop trigger button.
• All five Vision panel controls (Scan Y, Channel, Curve, Time, Energy).
• Global Volume, and the Fullscreen toggle — bind Fullscreen to a MIDI footswitch and go hands-free mid-set.

Separately, and without needing MIDI Learn: MIDI pitch bend re-pitches held notes live and drives the visual jog/scrub; the mod wheel (CC1) is wired to modulation; CC 64 acts as a sustain pedal — hold notes while it's down, release them all when you lift, in both the app and the plug-in; Panic hard-kills every voice instantly for stuck-note recovery.

AI Co-Piloting

MCP Control Standalone app, Mac only

MESA can run a local MCP server — the same protocol AI coding agents like Claude Code speak — so an agent can write and iterate Metal shaders, see real compile errors and rendered previews, push a shader onto the live terrain, sculpt the sound with real parameters, drive the Performance FX pad, steer Ableton Link, play the keyboard and pitch-bend wheel itself to audition what it built, and save the result as a preset. It's off by default; you turn it on from the sparkles icon in the status bar.

Connect

Or, for any other MCP client (Cursor, Windsurf, VS Code):

27 tools

Tool	What it does
mesa_catalog	Reference: the AU parameter map, all 26 modifier types, mod-matrix and arp names, and the exact Metal shader contract. Call this first.
mesa_state	Full live snapshot — preset, every parameter, mod matrix, Vision, arp, sampler, Performance FX, Ableton Link, telemetry.
mesa_list_shaders / mesa_get_shader	List and fetch shaders across all packs.
mesa_create_shader / mesa_update_shader	Write or edit a shader in My Shaders — compiles immediately, returns the real Metal compiler error on failure.
mesa_load_shader	Push a shader onto the live terrain by name.
mesa_preview_shader	Renders an actual 2D PNG of the shader — see it before it's live.
mesa_list_presets / mesa_get_preset / mesa_save_preset / mesa_load_preset	Browse, inspect, save, and recall full patches.
mesa_randomize	Roll a complete new patch — an unused shader plus a sound built around it, same as the dice button. Applies live with an auto-generated name; mesa_save_preset keeps it.
mesa_set_params	Set any subset of parameters by friendly name in one call.
mesa_set_mod	Set a mod-matrix slot, including the free-assign source/dest.
mesa_set_arp	Set arp on/hold/pattern/rate/octaves in one call.
mesa_note_on / mesa_note_off	Trigger and release a MIDI note directly — the agent can play the keyboard.
mesa_play_note	One-shot audition: plays a note and releases it after a duration, no second call needed.
mesa_pitch_bend	Set the pitch-bend wheel live, −1..+1 — re-pitches sounding notes immediately.
mesa_panic	Hard-kill every voice instantly, and reset the arp's held notes and any running sequence — for recovering from a stuck note.
mesa_set_volume	Set global output volume, 0–1 — downstream of the whole patch, ahead of the master limiter. Deliberately untouched by mesa_load_preset/mesa_randomize.
mesa_set_perf	Drive the Performance FX pad — enable, effect, engage, X/Y, and the drawn motion path (grid cells + rate).
mesa_set_link	Join or leave the Ableton Link session and propose a session tempo. (Enabling Start/Stop sync itself is still Ableton's own sheet.)
mesa_set_tempo	Set the arp/sequencer's BPM — the standalone app has no host transport, so rates like "1/8" need a real tempo to mean anything.
mesa_set_sequence	Play an explicit ordered step list, looping on its own clock — the fix for repeated-note patterns (which the pitch-sorted arpeggiator can't do) and for holding steady tempo (the model-to-tool round-trip is too slow to pace individual notes in real time).
mesa_sequence_stop	Stop a running mesa_set_sequence.

Reference

Specs

Formats	AUv3 plug-in + standalone app (universal purchase)
Platforms	iOS · macOS (Mac Catalyst, "Optimized for Mac")
Engine	Native C++17 DSP, Objective-C++ AU bridge, Swift/Metal UI
Polyphony	16 voices, oldest-note stealing
Unison	Up to 8 voices per note
Wavetable	64-frame morph, FFT mip-banked per frame for alias-free playback
Visual import	.vkograph · native/web-editor VKO1 Metal shaders · full modifier graph · 33 palettes
Shader library	93 shaders in the Starter Pack, live count shown in the browser header
Factory presets	57 patches across 8 categories, live count shown in the browser header
Modifiers	26 VFX node types, per-node wet/dry
FX chain	8-stage stereo rack — tape, flutter, waveshaper, chorus, delay (mix/time/feedback), reverb (mix/size/damp), lo-fi, tape-stop
Sequencer	303-shaped mono line in the DSP — note/gate/accent/slide/octave/tie plus per-step ratchet, velocity, probability and cutoff/morph parameter locks; 1–64 steps, bank of up to 64 patterns (add/duplicate/delete), beat-synced switching, swing; PLAY + tempo transport that defers to the host
Arpeggiator	8 orders (incl. as-played, chord, converge), 1–4 octaves up/down/alternating, gate, swing, ratchet, accent-every-N, BAKE-to-sequencer; one shared control set across plug-in and app
Motion	One selector: OFF / ARP / SEQ, sharing a clock. Under SEQ the keys transpose the line
Projects	.mesaproject — patch + shaders + full pattern bank + arp setup + transport + trim + MIDI mapping
Performance FX	Master-bus XY pad — 6 effects, drawable motion path, fullscreen; real DSP bypass when off
Output stage	Global Volume → master limiter, downstream of the whole patch and FX chain
MIDI	Full CC Learn (with an on/off switch) · pitch bend · sustain pedal (CC 64) · persistent bindings · notes-out to the host (AUv3) · pattern export as .mid
Sync	Ableton Link (standalone) via official LinkKit
MCP	Local server, 127.0.0.1:6372, 27 tools, Mac standalone only
AU identity	type aumu · subtype Mesa · manufacturer Tmpr