Disclaimer: This application is primarily AI-generated (built with Claude Code). The author takes no responsibility whatsoever for anything — use entirely at your own risk.
A modular audio workstation written in Rust with a real-time egui GUI, three complementary graph editors, a pattern sequencer, mixing and sampling, spatial audio, a 3D visualizer, and first-class AI-agent integration via MCP (Model Context Protocol).
I started playing with AI to build synth sounds and modules over the winter break of 2025/2026. It began simply, and I got sounds out surprisingly fast — so I figured it might be fun to have a little interface to make testing easier. It quickly became clear that, together with Claude Code, you could build fairly advanced interfaces and signal routing in no time. I fell for the egui framework along the way: fast and very capable, maybe not quite in line with today's reactive idioms — more bang-on, immediate-mode, a little last-century, which I rather like :-)
Once the sound modules were in decent shape, I thought it would be fun to load old Amiga modules, play them back, and see how they might be reimagined with a few more effects. I got reasonably far (there's a branch), but the more complicated formats never turned out well, so I let that idea go. I've been tinkering since the turn of the year, and the more you poke at something the more rabbit holes you fall into — there's always a new and interesting thing to build or understand.
I've now reached a point where it might be worth making public, in case anyone else wants to poke around and play. I know there are countless glitches and bugs, graphical bits that don't quite line up, and surely plenty of problems I'm not even aware of. But the important things are in place: MIDI support, building sounds with rich effect chains, a room simulation, a visualizer (which needs a lot more work :-) ), a sequencer, and a very simple sample bank. Take it for what it is — an experiment of mine that happened to grow rather large, and that might bring some use or enjoyment to someone out there. At the very least, I've learned a great deal — not just about Rust, but about audio programming and visualization too.
A fair warning: there's no manual and barely any documentation yet. So if you give it a try, treat it as an exploratory encounter — poke at things, see what happens, and discover how it works as you go :-)
A quick tour of what's inside — each item is described in more detail in its own section below.
- Modular synthesis — 70 module types (including 25 effects), patched freely over a DAG-based audio graph with live cable visualization, plus 68 built-in patches to start from
- Three graph workflows — the Rack builds per-voice audio patches, the Note Grid transforms note streams, and the Mod Grid runs reusable control-rate modulation graphs at global or per-track scope
- Deep modulation and scripting — the Mod Matrix and Mod Grid target parameters by stable address, while YAMS powers scripted control modules, audio-rate scripts, and modulation expressions
- Real-time GUI — Home, Rack, Notes, Mod, Pattern, Sequencer, Mixer, and Sample views remain interactive while the audio engine keeps playing
- MIDI — hardware MIDI input with velocity, pitch bend, mod wheel, and aftertouch
- Spatial & reverb — per-voice binaural placement with the Spatial Panner module (image-source early reflections + ITD/ILD direct path), plus FDN reverb, convolution, and modal-resonator effects
- Pattern sequencer — pattern-based composition with song arrangement, real-time recording, and per-pattern automation lanes, edited in the piano roll or a vertical tracker view
- Note processing & expression — pooled Note Grid graphs provide arpeggiation, ornaments, chord/strum, scale-quantize, humanize, delay, ratchets, scripting, and other reusable transformations, with graph binding at pattern or individual-note scope
- Sample bank — a simple sampler for importing, cropping, looping, and playing back your own samples
- Audio input & recording — record voice or live audio (mic/line-in) straight into the sample bank, or route the live input through an Audio Input module directly into a patch's module chain to process it with filters and effects
- WAV export — render your song offline (faster than real-time) to a WAV file at 16/24-bit or 32-bit float and 44.1/48/96 kHz, with adjustable duration and reverb/delay tail
- Headless rendering —
pertylizer renderturns a project into a WAV from the command line, with per-track solo/mute for stems and a JSON receipt (digests, peak, warnings) for scripts and CI - Project safety — atomic saves, autosave with crash recovery, derived unsaved-changes tracking, and undo/redo spanning the pattern, arrangement, mixer and rack views
- 3D visualizer — a separate Bevy app driven by OSC telemetry, with 27 audio-reactive effects, 11 scene presets, and 8 themes
- AI integration — 200+ MCP tools let agents build patches, Note/Mod graphs, arrangements, mixes, and analyses alongside you
A good place to start poking around is assets/examples/, which ships with a handful of things
to load and pull apart:
projects/— full songs you can open and play, spanning genres:Oxygene Dreams (80s Techno)andNeon Horizon, the Carpenter-styleEscape from Stockholm, the Finnish tangoKaru Sydän — Suomalainen Tango, the neurofunkNeuro F#m 174-extended, aSynth Pop a la Codex, two Amiga-tracker tributes (Classic Amiga moduleand the sample-bundledechoing), and aSidechain Demopatches/— individual instrument sounds, such asmoog_resonant_sweep,hybrid_resonator, and arobot-from-hell-audio-inputpatch that runs live audio input through the voice graph
See screenshots/README.md for a visual tour of the patch editor, the Mod Matrix YAMS script
editor, the sequencer and tracker, and 3D visualizer.
The current top-level workflow is split into eight focused views. The retired AWE view is no longer part of the application; its useful spatial work lives on in the per-voice Spatial Panner module.
- Home — start a project or instrument, open a patch or sample, and revisit recent projects
- Rack — instrument voice graph, effects, module groups, macros, and live patching
- Notes — the Note Grid pool and node editor for reusable note-event transformations
- Mod — the Mod Grid pool and node editor for always-on global or per-track control graphs
- Pattern — pattern browser with the full-window piano-roll or tracker editor
- Sequencer — song arrangement, tracks, placements, transport, and tempo map
- Mixer — instrument channels, return busses, sends, master processing, and metering
- Sample — sample import, recording, editing, looping, and preview
At its core, Pertylizer is a modular synthesizer. Every instrument is a voice graph you wire by hand — typically
oscillator → filter → amplifier → output — with envelopes and LFOs modulating any parameter you route them to, all
feeding a per-instrument effect chain. You can start from one of the built-in patches or from an empty graph and build
up from scratch.
- 70 module types (42 voice & synthesis modules, 25 effects, 3 inline visualizers) — oscillators (standard, wavetable, additive, granular, fractal, FM/math, sub, LA synth, vector, pad synth, chaotic), filters (ladder, SVF, biquad, formant), envelopes, LFOs, MSEG, mod matrix, ring mod, drift generator, sampler, audio input, and more
- 25 effects — delay, BBD delay, reverb, shimmer reverb, reverse gate reverb, chorus, ensemble chorus, flanger, phaser, univibe, distortion, waveshaper, compressor, limiter, EQ, tilt EQ, mid/side, crossover splitter, convolver, phase vocoder, vocoder, frequency shifter, granular FX, spectral blur, modal resonator
- 68 built-in patches — from acid bass and grand piano to fractal cosmos and spectral freeze pad, plus solo voice, choir, vocal tract and the SATB section voices
A handful of modules reach well past the usual subtractive toolkit:
- Fractal Oscillator — Weierstrass-function synthesis producing complex, evolving timbres
- Granular Synthesis — both as oscillator and real-time effect with grain cloud control
- Spectral Processing — phase vocoder, spectral blur, and partitioned convolution
- Physical Modeling — body resonance, mechanical noise, LA synth (bell/drum), modal resonator
- Generative Sequencing — Euclidean rhythm generator, Turing machine, random gates
- Voice & Formant Synthesis — a source–filter voice synth, a Kelly–Lochbaum vocal tract, and FOF/CHANT granular formant synthesis for vowel and choir-like tones
Modulation is first-class. Patch-local routings and project-level control graphs both target stable parameter addresses, and YAMS can supply anything from a compact expression to a complete scripted control module.
- Dynamic Mod Matrix — route any module output (
lfo-3.out,env-2.out) or per-voice macro (velocity, mod wheel, aftertouch, pitch bend, note) to any modulatable parameter on any module; every continuous parameter is a working destination - YAMS control scripts — optionally replace a routing's scalar amount with a small real-time expression language —
macros and context (note
age,gate), stateful operators (lag,slew,sah,phasor), math, and ternaries — compiled and evaluated per voice, editable live in the patch editor with compile and auto-format feedback - Mod Grid — build pooled control-rate graphs from LFOs, macros, transport, MIDI CC, audio taps, logic, and target nodes; run a graph globally or assign independent instances to tracks, with additive composition over automation
Space is built from ordinary graph modules rather than a separate subsystem, so it modulates and composes like everything else:
- Spatial Panner — a per-voice module that places each note in a virtual room: image-source early reflections
plus a binaural direct path (interaural time/level difference and head-shadow filtering). Its position (
x/y/z) is Mod-Matrix / YAMS modulatable, so notes can move independently. - Reverb & Shimmer Reverb — feedback-delay-network late reverb.
- Convolution — impulse-response spaces (plate / room / spring / hall).
- Modal Resonator — a bank of tuned resonances for room-mode and body character.
Songs are built from patterns — short clips of notes and automation — placed on tracks along an arrangement timeline. You can play parts in live or program them in the piano roll, loop sections while you work, and bounce the finished result straight to disk.
- Pattern-based sequencing with song arrangement (960 PPQN)
- Song repeat — loops the entire song; transport repeat button in the toolbar
- Pattern repeat — loops an individual pattern during playback; toggle in the piano roll toolbar
- Recording — real-time MIDI recording with count-in, quantize grid, and overdub mode
- Automation lanes — per-pattern parameter automation
- Tracker editor — a vertical, tracker-style per-pattern view (toggle with the piano roll) with note, voice, automation, and per-note expression columns
- Note Grid — reusable pooled graphs transform notes non-destructively as patterns play. Bind one graph to a whole pattern or override it on individual notes; graphs can be duplicated, shared, inspected in the tracker, or frozen into ordinary notes
- Note modules — scale quantize, chord/strum, arpeggiator, humanize, Euclidean generation, probability gate, note/step LFOs, note envelope, YAMS note transforms, delay/echo, and ratchet
- Per-note expression — glide/portamento, legato ties, vibrato, trigger probability, ghost/accent velocity, and gate length, set per note
- WAV export — offline render of the full song to WAV, faster than real-time, with selectable bit depth (16/24-bit, 32-bit float), sample rate (44.1/48/96 kHz), duration, and reverb/delay tail
Pertylizer isn't only synthetic — you can bring your own sound into the engine, whether from a file or straight off an input.
- Sample bank — a simple sampler for importing, cropping, looping, and playing back your own samples
- Audio input & recording — monitor and record mic/line-in into the sample bank, or feed it live into a patch via the Audio Input module to process external sound through the voice graph and effects
pertylizer render turns a saved project into a WAV file and exits. It opens no window and claims no audio device, so
it runs over SSH, in a container, or from a build script:
pertylizer render --input song.ptz --output song.wav --seconds 60 --tail-seconds 4- Renders the full chain — send/return busses, return effects, and master effects included, because the job is to produce the file the project actually sounds like. The offline analyzers default the other way, on purpose
- Picks apart the mix —
--solo-trackand--mute-tracktake a track id or a unique track name and repeat, so one project yields a stem per part without ever being edited - Chooses its own precision —
--bit-depthspans 8/16/24/32-bit integer and 32-bit float; float is the default because it is lossless against the renderer's own output.--sample-rateis independent of any device - Reports machine-readably — a JSON receipt goes to stdout, or to a file with
--result-json. It carries SHA-256 digests of both the project read and the WAV written, the audio's rate/depth/frames/peak, which tracks were audible, any warnings, and the argv that produced it — so a harness can diff two renders without decoding the audio, and reproduce either one
The input is never written to, and --protocol-version pins the contract so a script can tell a changed CLI from a
changed song.
Losing work is the one failure a creative application never gets forgiven for, so the save path is built to make it hard:
- Atomic saves — a project is serialized in full before the destination is touched, then written through a temp-and-rename. A disk error or a crash mid-write cannot truncate the last good save
- Autosave and crash recovery — periodic snapshots land in a private recovery directory, never on top of the file you opened, so "close without saving" keeps meaning what it says. A snapshot is deleted once the work it protects is safe (a manual save, or discarding the changes), which means one still present at startup is itself the evidence that the last run ended with unsaved edits — no lock file or shutdown flag needed
- Unsaved-changes tracking that is derived, not reported — the title bar's
*follows edit revisions on the song, sample library, engine graph, patch layout, and global state, so a change made from the GUI, from MCP, or by undo cannot forget to announce itself. The same predicate gates autosave and the close prompt, which is why it has to be right - Undo/redo across the views — pattern and arrangement edits, mixer and master moves, effect-chain reordering, and rack changes share one history
Pertylizer exposes 200+ MCP tools that let AI agents (Claude Code, Claude Desktop, or any MCP-capable client) build instruments and graph assets, compose songs, edit patterns, set parameters, mix, render and analyze audio, and play notes in real time — all while the synth keeps running.
- Streamable HTTP on
http://127.0.0.1:9850/mcp(enabled by default in GUI mode) - stdio transport via
cargo run -- --headless - Audio analysis tools (
analyze_harmony,analyze_section,analyze_mix_bus) give agents quantitative, deterministic feedback on harmony, mix balance, and per-track contribution - Graph authoring tools create, inspect, duplicate, bind, and edit pooled Note Grid and Mod Grid graphs without bypassing the same validation used by the GUI
- Auto-inference (
get_instrument_profiles) classifies instrument roles (drums/bass/lead/pad/pluck/FX) with confidence scores so agents can compose without manual tagging
See docs/README_MCP.md for the full integration guide, tool catalog, and example workflows.
A few principles hold the whole thing together:
- Modular patching — connect modules freely via a DAG-based audio graph with cable visualization
- Pooled graph assets — Note Grid and Mod Grid graphs are stored once in the song and referenced from patterns, notes, or track assignments
- Multitimbral — per-instrument voice allocation and effect chains
- Mixing & routing — per-instrument, return-bus, and master effect chains, with sends (including bus-to-bus) and per-channel level/pan/mute/solo
- Real-time safe — commands and events use lock-free ring buffers; sequencer edits publish immutable
Songsnapshots throughArcSwap, so the audio thread never takes the editor's song lock - MIDI — hardware MIDI input with velocity, pitch bend, mod wheel, aftertouch
- Audio input — monitor and record mic/line-in into the sample bank, or feed it live into a patch via the Audio Input module to process external sound through the voice graph and effects
- OSC telemetry — real-time spectrum, RMS, note events, and transport state streamed over UDP at 30 Hz (enabled by
default,
--no-oscto disable) — this is what drives the 3D visualizer
A separate application (visualizer/) that receives OSC telemetry from the synth and renders real-time 3D visuals
driven by audio analysis. It runs as its own binary, so the synth stays lean whether or not you use it.
Effects are organized into layered scene slots:
| Slot | Effects |
|---|---|
| Terrain | Base Floor, FFT Bars, Waveform Ring, Spectral Waterfall, Pulse Terrain, Spectral Origami, Phase Rings, Voronoi Shatter, FFT Terrain, Cyber Wireframe |
| Hero | CPU Overdrive Core, Flux Supernova, Fractal Pulse, Ferrofluid Tendrils, Note Tree, Orbital Satellites |
| Ambient | Centroid Nebula, Spectral Cathedral, Reaction Diffusion, Spectral Aurora |
| Transients | Note Particles, Velocity Meteors, Harmonic Ribbons, Chord Bloom, Neon Calligraphy, Instrument Cubes, Beat Fracture |
- Classic Pertylizer — Spectral Waterfall + Note Particles
- The Matrix — Pulse Terrain + CPU Overdrive + Centroid Nebula + Velocity Meteors
- Sacred Geometry — Spectral Origami + Fractal Pulse + Spectral Cathedral + Chord Bloom
- Magnetic Storm — Waveform Ring + Ferrofluid Tendrils + Centroid Nebula + Phase Rings + Harmonic Ribbons
- The Exploding Sun — FFT Bars + Flux Supernova + Neon Calligraphy + Note Particles
- Metallic Orchestra — Base Floor + Fractal Pulse + Centroid Nebula + Instrument Cubes
- Earthquake — Voronoi Shatter + Ferrofluid Tendrils + Velocity Meteors + Note Particles
- Spectrum City — FFT Terrain + Note Tree + Reaction Diffusion + Chord Bloom
- Living Forest — Pulse Terrain + Note Tree + Centroid Nebula + Harmonic Ribbons + Note Particles
- Neon Grid — Cyber Wireframe + Orbital Satellites + Spectral Aurora + Beat Fracture
- Arctic Station — Cyber Wireframe + Flux Supernova + Spectral Aurora + Note Particles + Beat Fracture
Neon (default), Metal, Glass, Space, Synthwave, Ember, Arctic, Void
Orbit (default), Top-Down, Front, Fly-Through, Free Orbit
- Dolly-zoom triggers automatically on bass drops
- Auto-cut cycles through camera modes every ~20 seconds
Press H to show a semi-transparent overlay with:
- Visuals — active theme, camera mode, auto-cut state, scene composition (terrain/hero/ambient/transients)
- Audio analysis — RMS levels, peak levels, spectral centroid (Hz), spectral flux
- Transport — BPM, beat position, beat phase, voice count
- Performance — FPS, frame time (ms), CPU usage, event drops, data staleness
- Technical — FFT bin count, OSC protocol version
# Start the synth first (OSC telemetry enabled by default)
cargo run
# In another terminal, start the visualizer
cd visualizer && cargo run| Key | Action |
|---|---|
Z – M |
Play notes (C3–B3) |
Q – I |
Play notes (C4–C5) |
2, 3, 5, 6, 7 |
Black keys (sharps/flats) |
- / + |
Shift octave down / up |
| Key | Action |
|---|---|
Left / Right |
Previous / next scene preset |
Up / Down |
Zoom in / out |
R |
Random scene (procedurally generated) |
T / Shift+T |
Next / previous theme |
C / Shift+C |
Next / previous camera mode |
V |
Toggle auto-cut (cycles camera modes every ~20s) |
F |
Toggle fullscreen |
P |
Save screenshot (PNG) |
H |
Toggle debug HUD |
- Language: Rust 1.98+ (edition 2024)
- Audio: cpal (cross-platform I/O)
- GUI: egui/eframe with custom knobs, meters, scopes, and spectrum analyzer
- MIDI: midir
- DSP: PolyBLEP oscillators, SVF/biquad/ladder filters, FFT via realfft
- MCP: rmcp + axum (Streamable HTTP on port 9850)
- OSC: rosc (Open Sound Control over UDP)
- Visualizer: Bevy 0.19 (3D rendering)
- Concurrency: lock-free ringbuf, parking_lot
# Build
cargo build
# Run with GUI (MCP + OSC telemetry enabled by default)
cargo run
# Run without OSC telemetry
cargo run -- --no-osc
# Run headless (no GUI, MCP server on stdio)
cargo run -- --headless
# Render a saved project to WAV and exit — no GUI, no audio device
cargo run -- render --input song.ptz --output song.wav --seconds 60
# Tests, lints, formatting
cargo fmt --check
cargo build
cargo clippy --workspace --all-targets
cargo test --workspace
cargo doc --workspace --no-deps--workspace is required rather than optional: default-members selects only
the pertylizer package, so without it every other crate's tests, benches and
examples go unbuilt. cargo doc is in the list because [build] warnings = "deny" covers rustdoc too — a broken intra-doc link fails CI while the other
commands stay silent.
| Crate | Description |
|---|---|
synth_core |
Domain types, module traits, audio abstractions |
synth_config |
Runtime config (pertylizer.toml) shared by app & visualizer |
synth_dsp |
DSP primitives: oscillators, filters, delay lines, FFT |
synth_sampler |
Sample loading, playback, and waveform analysis |
synth_sequencer |
Pattern and song sequencing |
synth_modules |
70 module types including 25 effects |
synth_engine |
Audio engine: voice allocation, modular graph, mixing |
synth_mcp |
MCP server with 200+ tools for AI agent integration |
synth_osc |
OSC telemetry sender (spectrum, notes, transport over UDP) |
synth_osc_protocol |
Shared OSC protocol definitions for synth and visualizer |
pertylizer |
Main application: GUI, audio I/O, MIDI |
visualizer |
Bevy 3D visualizer driven by OSC telemetry (separate binary) |

