Introduction

Patches is a modular audio instrument with a text-based patch language. You describe a graph of modules — oscillators, filters, envelopes, sequencers, effects — and how they connect; the engine runs the graph in real time. Save the file and Patches swaps in the new graph without interrupting audio or resetting module state, so editing the patch is itself the development cycle.

Why Patches?

Most software modular systems present a graphical reproduction of a Eurorack-style hardware modular setup. You drag patch cables between ports, turn knobs, move sliders. This is satisfying and creatively rewarding, but it isn’t the only way to work.

Patches sets the visual interface aside and concentrates on two things: a clear language for describing patches, and a fast, real-time-stable engine for running them. The language is supported by a full Language Server Protocol implementation, so any compatible editor can offer autocomplete, inline hints, and navigation between definitions.

Working in text makes some abstractions natural that would be awkward in a visual environment. Three examples:

• Per-cable scaling, offset and clipping. Signals can be amplified, offset, or mapped into and bounded within a constant range with an annotation on the cable connection.
• Templates. Define a sub-patch once with parameters, then instantiate it multiple times with different values.
• Multi-channel modules. A mixing desk or multi-tap delay can be declared with whatever number of channels you need, each with its own parameters, inputs, and outputs.

Three ways to run a patch

Patches has no single intended workflow. The same .patches file works in any of these contexts:

As a CLAP plugin in a DAW. Load the Patches plugin in REAPER, Bitwig, or any CLAP host. Point it at a patch file, drive it from MIDI tracks, automate its parameters, save with the project. Use this when you want a custom synth voice inside a larger production.

As a standalone instrument driven by external MIDI. Run patch_player hello.patches, connect a controller, play. Use this when you want a hardware-style instrument with no DAW in the loop.

As a self-contained piece driven by built-in sequencing. A patch can include the tracker, step sequencer, and clock modules — its own note source. Run it in the player and the piece plays itself. Use this when the patch is the composition.

The DSL, module set, and audio engine are identical across all three. Pick the surface that fits the task.

A first patch

patch {
    module osc : Osc { frequency: 440Hz }
    module out : AudioOut

    osc.sine -> out.in
}

Save as hello.patches and run:

patch_player hello.patches

A 440 Hz sine tone. Change the frequency to 220Hz, save, and the pitch drops — no click, no restart. Change osc.sine to osc.sawtooth for a brighter timbre. Ctrl-C to stop.

What’s next

• Mental model — how patches are built from modules, ports, cables, and signal kinds. Read this before the DSL chapters; it is the conceptual foundation everything else assumes.
• Installation — getting the player, CLAP plugin, and VS Code extension onto your machine.
• Basic operation — running existing patches in each of the three workflows.
• The DSL — the patch language in detail.
• Patch authoring — building real instruments and pieces.
• Module reference — every built-in module, its ports, and its parameters.
• Extending Patches — writing modules in Rust, or as native plugins via the ABI.
• Internals — the audio engine, CLAP plugin, and language server.

Mental model

A patch is a directed graph. Boxes are modules; arrows are cables. A module reads from its inputs, computes, and writes to its outputs once per audio sample. Cables carry the output of one module to one or more inputs of others.

That is the whole model. Everything else — the DSL syntax, the polyphony rules, the live reload behaviour — is a way of building and editing this graph.

Modules

A module is a unit of computation with a fixed set of named inputs and outputs. Examples:

• An oscillator has no inputs (or some control inputs) and produces an audio output.
• A filter has an audio input and one or more control inputs (cutoff, resonance), and produces a filtered audio output.
• An envelope has a gate input and a trigger input, and produces a control signal that rises and falls.
• An output module has an audio input and writes to the soundcard.

The set of ports is defined by the module’s type. An instance of the type carries its own state — an oscillator’s phase, a filter’s history, an envelope’s position. State is private to the instance.

Ports and signal kinds

Each port has a name (in, out, cutoff, gate, voct) and a fixed kind. The kind decides what can connect to it.

• Audio — a stream of audio samples. Centred on zero, typically in the range −1 to +1.
• Control voltage (CV) — a stream of slow-changing modulation values. The convention is V/oct: 1 unit = 1 octave. Pitch and many modulation signals use this.
• Gate — a level held high (≥ 0.5) or low (< 0.5). Tells an envelope a note is being held.
• Trigger — a sub-sample-accurate event encoding. 0.0 means “no event on this sample”; a value in (0.0, 1.0] is the fractional position of an event within the sample. Tells an envelope to restart.
• Stereo — a pair (L, R) of audio samples on one cable. Symmetric stereo modules use a single stereo port rather than two mono ports.

Audio, CV, and gate all ride on the same mono Audio cable layout — the engine doesn’t distinguish them, and the difference is only how a module interprets what it reads. You can deliberately abuse this: feed an audio signal into a CV input for aggressive modulation, or use an envelope’s output as audio for a one-shot percussive sample.

Trigger is a different cable layout. It encodes sub-sample event positions, not levels, and the connection validator rejects audio↔trigger wiring in either direction — use the appropriate event source or a conversion module. Poly cables have further distinct layouts for transport frames and packed MIDI events; same rule applies, no implicit coercion across layouts.

Mono and poly

Cables come in two flavours: mono (one sample per audio tick) and poly (one sample per voice per tick, typically 16 voices). A module type is either mono or poly throughout — there is Osc (mono) and PolyOsc (polyphonic), Adsr and PolyAdsr, and so on.

A mono cable cannot connect to a poly input or vice versa. Use a MonoToPoly to broadcast one mono signal to every voice, and PolyToMono to sum voices down to a single mono signal.

Stereo and mono interact more permissively: a mono source feeding a stereo input is silently broadcast (L = R = source). The reverse — stereo into mono — is an error; if you want it, route through a StereoSplitter.

Cables

A cable connects exactly one output to exactly one input. To split a signal to several destinations, draw several cables from the same output (this is free — no mixing node required). To combine signals into one input, route them through a mixer module — the destination only accepts one cable.

A cable can carry a scale factor that multiplies the signal as it passes:

osc.sine -[0.3]-> out.in

This is a per-cable gain; it is useful for trimming levels, scaling modulation depth, or inverting (-1.0).

Cable delay

Cables in cycle-bearing regions of the graph impose a one-sample delay: a module reads what its neighbours wrote on the previous tick. This is what makes feedback loops well-defined — a feedback cable carries the previous tick’s value, and modules in a cycle can be evaluated in any order.

In acyclic (feedback-free) regions, the planner fuses the chain so consumers read producers’ current-tick output. This is invisible to the patch author — the audio result matches the conceptual model — but it removes the one-sample delay that would otherwise accumulate audibly across a long signal chain.

A patch is a file

A patch is described in a .patches file: a single text document that declares modules, sets their parameters, and draws cables between them. There is no project file, no binary patch format. You edit the file; the engine runs the graph the file describes.

When you save, the engine builds the new graph and swaps it in without stopping the audio. Module instances whose name and type are unchanged carry their state across the swap. This is the REPL property — small edits sound like parameter tweaks, not restarts.

Visualising the graph

The graph can be rendered as an SVG diagram with patches-svg (covered in Visualising patches). Reading the diagram is a useful way to understand a patch you didn’t write; writing one rarely needs the picture.

Installing the player

patches-player is the standalone command-line player. Give it a .patches file and it opens an audio device, runs the patch, watches the file, and hot-reloads on save. Two install paths: a prebuilt release archive, or a build from source.

Prebuilt release archive

Each stable GitHub release attaches:

Prerelease tags ship only the zip on Windows; the MSI is built on stable tags. Linux has no prebuilt artefact yet — see Build from source below.

Each archive contains:

• patch_player (the binary; patch_player.exe on Windows)
• Patches.clap — the CLAP plugin, covered in the next chapter
• a matching .vsix for the VS Code extension
• examples/ — the patches under examples/ in the repo
• patches-manual.pdf — this manual
• on macOS: macos-unquarantine.sh

macOS

tar -xzf patches-<version>-macos-aarch64.tar.gz
cd patches-<version>-macos-aarch64
./macos-unquarantine.sh
./patch_player examples/square_440.patches

The binary is ad-hoc-signed but not notarised, so Gatekeeper marks it quarantined on first download. macos-unquarantine.sh strips the quarantine flag from patch_player, Patches.clap, any bundled native module dylibs, and the bundled .vsix. As a convenience it also installs Patches.clap into ~/Library/Audio/Plug-Ins/CLAP/ and (if the code CLI is on PATH) installs the bundled VS Code extension — covered in the next two chapters. Without the quarantine strip the first run fails with a “cannot be opened because the developer cannot be verified” dialog. See Unsigned binaries for the underlying mechanism and manual overrides.

Drop patch_player somewhere on your PATH (e.g. ~/.local/bin/, /usr/local/bin/) if you want to run it without a path prefix.

Windows

Two install paths. The MSI is the default — use it unless you specifically want a portable, no-install copy.

MSI (recommended). Double-click patches-<version>-windows-x86_64.msi and accept the elevation prompt. The installer is not signed, so SmartScreen will warn on first run — click More info → Run anyway. It places:

• patch_player.exe, the manual PDF, and the LICENSE into C:\Program Files\Patches\
• Patches.clap into C:\Program Files\Common Files\CLAP\ (the standard CLAP system path)
• the bundled .patches examples into C:\Users\Public\Documents\Patches\examples\
• registers .patches as a file type whose default opener is patch_player.exe, so double-clicking a .patches file launches it
• adds an App Paths entry, so patch_player resolves from any cmd / PowerShell prompt without manual PATH editing
• adds a Start Menu Patches group with shortcuts to the examples folder and the manual

The VS Code extension is not included in the MSI — install it via Extensions → Install from VSIX… using the .vsix from the zip archive, or from the Marketplace if/when it lands there.

Zip (portable). Extract patches-<version>-windows-x86_64.zip with Explorer or tar -xf from PowerShell. Right-click patch_player.exe → Properties → tick Unblock before first run, or SmartScreen will refuse to launch it. Then:

patch_player.exe examples\square_440.patches

The zip is the lightweight option — no installer, no registry changes, no Start Menu entries — and it stays available alongside the MSI on every stable release.

Linux

No prebuilt artefact yet. Build from source.

Build from source

The player builds on macOS, Linux, and Windows with a stable Rust toolchain. From a checkout of the repo:

cargo install --path patches-player

This installs patch_player into ~/.cargo/bin/. If that directory is on your PATH, the binary is immediately runnable.

To build without installing — useful when iterating on the source — use cargo build --release -p patches-player; the binary lands at target/release/patch_player.

Linux dependencies

CPAL needs ALSA development headers. On Debian/Ubuntu:

sudo apt install libasound2-dev

On Fedora:

sudo dnf install alsa-lib-devel

JACK is supported through ALSA’s JACK bridge or PipeWire’s JACK shim — no separate dependency on the JACK library is required.

macOS / Windows

No system packages required beyond a working Rust toolchain (rustup default stable). On Windows, cargo install uses the MSVC toolchain by default; the GNU toolchain is untested.

Verification

patch_player --version    # not yet implemented; use the next check
patch_player examples/square_440.patches

A short pulse-width-modulated square at ~100 Hz plays through the default output device. Ctrl-C to stop. If you see the TUI, hear the tone, and see “audio: started” in the log pane, the player is working.

If the player exits with “no default output device”, pass --output-device <name> (run with --list-devices to see what is available).

Installing the CLAP plugin

The CLAP build is a single dynamic library that ships two descriptors: Patches (an instrument) and Patches FX (an audio effect). Most hosts surface them in two slots — instruments and effects — from the same .clap bundle. No separate effect build, no extra install step.

Prebuilt release archive

The release archives described in the previous chapter contain Patches.clap alongside patch_player. To install just the CLAP plugin from those archives, copy the bundle into your CLAP search directory:

macOS

tar -xzf patches-<version>-macos-aarch64.tar.gz
cd patches-<version>-macos-aarch64
./macos-unquarantine.sh

macos-unquarantine.sh strips the Gatekeeper quarantine flag from Patches.clap and copies it into ~/Library/Audio/Plug-Ins/CLAP/. For a manual install, skip the script and run:

mkdir -p ~/Library/Audio/Plug-Ins/CLAP
cp -R Patches.clap ~/Library/Audio/Plug-Ins/CLAP/
xattr -dr com.apple.quarantine ~/Library/Audio/Plug-Ins/CLAP/Patches.clap

If a host rejects the plugin with “cannot be opened” after install, repeat the xattr -dr step and rescan.

Windows

Right-click Patches.clap → Properties → Unblock, then copy:

mkdir "%LOCALAPPDATA%\Programs\Common\CLAP"
copy Patches.clap "%LOCALAPPDATA%\Programs\Common\CLAP\"

The system-wide path C:\Program Files\Common Files\CLAP\ works too but requires elevation.

Linux

No prebuilt artefact yet — build from source.

Build from source

The fastest macOS recipe is the deploy.sh script at the repo root. It release-builds patches-clap, strips quarantine from any previous install, and copies the dylib into ~/Library/Audio/Plug-Ins/CLAP/Patches.clap. It also packages and installs the VS Code extension; read the script first if you only want the plugin.

./deploy.sh

For the underlying steps on any OS:

cargo build --release -p patches-clap

This produces a platform-specific dylib in target/release/:

The destination filename ends in .clap regardless of source extension — hosts identify the bundle by name and load whatever shared object is inside.

Linux dependencies

Same as the player: ALSA dev headers (sudo apt install libasound2-dev or equivalent).

Verification

1. Start your DAW (REAPER, Bitwig, Ableton 11.3+, FL Studio 21.2+, Studio One 6.5+, …).
2. Trigger a plugin rescan if the host doesn’t scan on startup.
3. Patches should appear under the Instruments category.
4. Patches FX should appear under the Effects (or Audio Effects) category.
5. Load Patches on a MIDI track, open its UI, and load a patch from examples/ via the file picker.

If only one of the two descriptors shows up, the host is likely filtering by feature tag; check both the instrument and effect sections of the plugin browser. The dylib is the same — no second install needed.

If neither shows up:

• macOS — quarantine. xattr -l ~/Library/Audio/Plug-Ins/CLAP/Patches.clap will list it if present; re-run macos-unquarantine.sh or strip manually.
• Windows — Unblock the file via Properties; SmartScreen blocks load until you do.
• All OSes — confirm the host is actually scanning the directory you copied to. Some DAWs maintain a per-host CLAP path list that doesn’t include the user-local default.

Installing the VS Code extension

The VS Code extension provides syntax highlighting and language-server features (diagnostics, hover, go-to-definition, completions) for .patches files. The language server itself is patches-lsp, a native binary bundled inside the VSIX for the current platform.

The extension is platform-specific: each VSIX contains the patches-lsp binary for one OS / architecture. Install the one that matches the machine VS Code is running on.

The release archives contain the matching VSIX for that OS already; the file is also attached as a separate asset on each release for people who only want the extension.

Install from VSIX

From a terminal:

code --install-extension patches-vscode-<platform>-<ver>.vsix

Or from inside VS Code:

1. Extensions (Cmd+Shift+X / Ctrl+Shift+X).
2. Three-dot menu → Install from VSIX…
3. Pick the VSIX.

Reload the window. Open any .patches file — the Patches DSL extension activates, the editor gains syntax colouring, and the LSP starts in the background.

macOS: bundled LSP quarantine

If patches-lsp itself was downloaded as part of the release archive it will likely be quarantined. The extension auto-starts the bundled binary on first activation; if it fails (the Patches DSL: Output panel shows “operation not permitted” or a Gatekeeper dialog appears), strip quarantine from the binary inside the installed extension:

xattr -dr com.apple.quarantine \
  ~/.vscode/extensions/vulpus-labs.patches-vscode-*/server/

Then Developer: Reload Window. Running macos-unquarantine.sh on the release archive avoids this — the script clears the flag on the .vsix and, if the code CLI is on PATH, installs the extension for you. code --install-extension preserves the cleared attribute, so the bundled LSP starts cleanly.

Windows: bundled LSP unblock

If the LSP fails to start on Windows, locate the installed extension under %USERPROFILE%\.vscode\extensions\vulpus-labs.patches-vscode-*, open server\patches-lsp.exe → Properties → Unblock, and reload the window.

Build from source

From a repo checkout, the canonical recipe is the per-platform build script:

./scripts/package-vsix.sh darwin-arm64
# or: darwin-x64 | win32-x64 | linux-x64
# omit the arg to build all four

This release-builds patches-lsp for the requested target, copies the binary into patches-vscode/server/, compiles the TypeScript client, and produces a VSIX under dist/. Then:

code --install-extension dist/patches-vscode-darwin-arm64-*.vsix --force

./deploy.sh runs this for the current host architecture and reloads the extension into VS Code in one step — the recommended path during local development on macOS.

Linux dependencies for building

Building patches-lsp needs ALSA dev headers (sudo apt install libasound2-dev); building the VSIX itself needs Node.js 20+ and npx.

Configuration

The extension contributes two settings of note (both under Patches DSL in the settings UI):

• patches.lsp.path — override the bundled binary with an alternative patches-lsp (e.g. a debug build under target/debug/). Leave empty to use the bundled binary, or to fall back to PATH lookup if no bundle is present.
• patches.modulePaths — directories or specific dylib files to scan for FFI module bundles. Required if you reference modules from external bundles (e.g. patches-vintage) in a .patches file — without it the LSP can’t resolve their descriptors and hover/diagnostics will be incomplete.

Verification

1. Open a .patches file (any from examples/ will do).
2. Syntax should be coloured: keywords, module type names, ports, parameters distinct.
3. Hover over a module type name (e.g. Osc) — a tooltip describes the module and lists its ports.
4. Introduce a typo (Osce); a red squiggle appears with a “Unknown module type” diagnostic.

If steps 3–4 don’t work the LSP isn’t running. Open Output → Patches DSL in the bottom panel for the server log; the most common cause on macOS is the quarantine flag covered above.

Unsigned binaries

The Patches release binaries are unsigned. There is currently no Apple Developer ID and no Windows code-signing certificate behind the project. macOS and Windows both treat downloaded unsigned binaries with suspicion, so first-run requires an explicit override.

This is policy on the publisher’s side, not a security flaw on yours — but the override mechanisms are real protections, so it’s worth knowing what each one does.

macOS — Gatekeeper

When macOS downloads a file from the internet it tags it with an extended attribute, com.apple.quarantine. Gatekeeper checks this attribute on first launch: if the file is unsigned (or signed by an unrecognised developer), the OS refuses to run it with a “cannot be opened because the developer cannot be verified” dialog.

The release binaries are ad-hoc signed — codesign --sign - — which satisfies the dyld loader (the dylib will resolve and link) but not Gatekeeper (no trusted certificate). The quarantine flag must be removed for first launch.

The release archive ships macos-unquarantine.sh for this:

./macos-unquarantine.sh

It runs xattr -dr com.apple.quarantine over patch_player, Patches.clap, any bundled native module dylibs, and the bundled .vsix. It also installs Patches.clap into ~/Library/Audio/Plug-Ins/CLAP/ and, if the code CLI is on PATH, installs the bundled VS Code extension. Steps that have no matching input are skipped silently; the script is idempotent. Manual equivalent for clearing a single file:

xattr -dr com.apple.quarantine /path/to/Patches.clap

xattr -l <file> lists extended attributes if you want to check whether the flag is still set.

Once cleared, the binary launches normally — Gatekeeper only checks on first launch. Re-downloading or re-extracting from the original archive re-applies the flag.

Windows — SmartScreen and Mark of the Web

Windows downloads from the internet get tagged with a Mark of the Web (an alternate data stream named Zone.Identifier). When you launch a tagged executable, SmartScreen interposes a “Windows protected your PC” dialog and refuses to run unrecognised unsigned binaries by default.

This applies equally to the MSI installer and to individual binaries in the zip archive — the MSI is not code-signed, so SmartScreen warns on it just as it does on the loose .exe. From the warning dialog, click More info → Run anyway to proceed.

For loose files in the zip archive, the override is per-file:

1. Right-click the file (.exe, .dll, .clap, .vsix).
2. Properties → General tab.
3. Tick Unblock at the bottom.
4. OK.

This clears the Mark of the Web for that file. SmartScreen won’t prompt on subsequent launches.

PowerShell equivalent for scripting:

Unblock-File -Path .\patch_player.exe
Unblock-File -Path .\Patches.clap

Get-Item .\patch_player.exe -Stream Zone.Identifier lists the zone-identifier stream if it is still present.

Linux

Linux distributions have no equivalent gating — the binary runs as soon as it has the executable bit set. If you downloaded a build artefact without the executable bit, restore it:

chmod +x patch_player

That’s the whole “override”.

Why no signing?

Both Apple and Microsoft signing programs require ongoing developer identity verification and a non-trivial annual fee. Patches is a small project and signing has not been prioritised. When that changes, these workarounds become unnecessary.

For now: clear the quarantine flag, tick Unblock, run the binary.

Running a patch in the player

patch_player (built from the patches-player crate; binary name patch_player, sometimes still referred to as patches-player) is the standalone command-line player. It opens an audio device, loads a .patches file, runs it, and watches the file for changes.

The smallest run

patch_player examples/square_440.patches

A pulse-width-modulated square plays through the default output device. The terminal switches into the TUI — log pane, CPU pane, status bar. Ctrl-C exits cleanly.

If the patch fails to compile, the player renders diagnostics with source spans to stderr (still in TUI mode) and keeps the previous patch running. Fix the error and save; the new graph swaps in.

MIDI

When the player starts it auto-connects to every MIDI input port currently visible to the system. There is no UI for choosing a device — plug the controller in before launching, and it appears. Events from any connected port feed into the patch’s MIDI source modules (MidiToCv, PolyMidiToCv, MidiCC, etc.).

If no ports are available, the player logs a warning and keeps running; you can still drive sequenced patches that don’t need external input.

To connect a new device after launch, exit and re-run — MIDI ports are opened once at startup. Re-running is cheap; the patch reloads fresh.

Audio routing

Use --list-devices to see what CPAL exposes:

patch_player --list-devices

Then point at a specific device with --output-device:

patch_player --output-device "External Headphones" examples/square_440.patches

--input-device <name> opens a capture device for modules that process input audio (AudioIn and friends). Names are matched literally; if the host system reports a device as "Built-in Microphone (Builtin)", that whole string is the argument.

--oversampling <1|2|4|8> raises the internal sample rate before downsampling to the device rate — useful for alias-heavy patches (unfiltered saw, hard sync). Default is 1 (no oversampling).

Recording

patch_player --record session.wav examples/tracker_three_voices.patches

The output stream is forked into a 16-bit PCM stereo WAV at the device’s sample rate. The file finalises when the player exits (Ctrl-C is fine; it runs the recorder’s Drop impl on the way out). Crash the process and the WAV header will be incomplete.

Hot-reload

The player watches the patch file. Save it, and the engine builds the new graph and swaps it in without stopping the audio. Module instances whose name and type are unchanged keep their internal state across the swap — an oscillator’s phase, a delay’s buffer, an envelope’s position — so small edits sound like parameter tweaks rather than restarts.

This is the development REPL described in the introduction. See The edit-reload cycle for the rules on what survives a reload, what resets, and how to structure patches to make iteration smooth.

Other flags

patch_player with no arguments prints the full flag list. Common options:

--no-tui is most useful for headless smoke runs and CI — it just prints to stdout and reads from stdin, no terminal raw mode.

Exiting

Ctrl-C in the TUI. The player tears down the audio stream, finalises any WAV recording, and restores the terminal. If the terminal looks broken after an unclean exit, reset will fix it.

Running a patch in a DAW

The CLAP plugin loads a .patches file inside any CLAP host and runs it under that host’s transport, audio routing, and MIDI. The same DSL, modules, and engine — just hosted, with the DAW responsible for audio I/O and clock instead of the player binary.

The bundle ships two descriptors from a single dylib:

• Patches — an instrument. Appears under the host’s instrument browser. Takes MIDI in, produces stereo audio out.
• Patches FX — an audio effect. Appears under the host’s effect browser. Takes stereo audio in, produces stereo audio out, still accepts MIDI for control.

Pick the descriptor that matches what you want to do; the underlying engine is the same.

Loading a patch

1. Add Patches to a MIDI track (or Patches FX to an audio track).
2. The plugin window shows a small webview-based GUI with a header strip carrying the current patch path and two buttons — Browse… and Reload — and a tabbed body (Modules, Diagnostics, scope/meter taps if the patch declares any).
3. Hit Browse… and pick a .patches file. The plugin compiles it, swaps the graph in, and starts producing audio on the next block.

Diagnostics appear in the Diagnostics tab’s Event log. If a file fails to compile, the plugin reports the error there and keeps the previous patch running.

Host examples

REAPER

• Insert → Virtual Instrument on New Track → pick Patches from Instruments (CLAP).
• Or, on an audio track, FX → Add → Patches FX.
• MIDI routing is automatic from the track’s MIDI items.
• Options → Preferences → Plug-ins → CLAP lists the directories scanned; the user-local default (~/Library/Audio/Plug-Ins/CLAP/ on macOS) is included by default.

Bitwig Studio

• Drop Patches onto an instrument track from the device browser under Instruments → CLAP.
• For audio processing, drop Patches FX onto an audio track.
• Bitwig rescans on launch; trigger a manual rescan via Settings → Locations → CLAP plug-ins → Refresh if a freshly installed bundle doesn’t appear.

Other CLAP hosts (Ableton Live 11.3+, FL Studio 21.2+, Studio One 6.5+) follow the same pattern: instrument bucket for Patches, effect bucket for Patches FX.

MIDI

The host routes MIDI to the plugin. For Patches that means notes flow into MidiToCv / PolyMidiToCv modules and CC traffic flows into MidiCC modules. The plugin doesn’t open MIDI ports of its own — the host handles all device selection.

Self-contained patches (those driven by a MasterSequencer / PatternPlayer rather than MidiToCv) ignore inbound MIDI and play themselves. Sequenced and externally-driven approaches can be mixed within a single patch.

Automation

Host controls declared in a patch via the knob / slider / toggle / trigger declarations show up in the host’s parameter list for automation, modulation, and per-track recall. Manipulate them from a DAW lane the same way you would any other plugin parameter.

Parameter values move through the persisted-settings layer, so an automated value at the start of playback is restored from the saved project state.

Project save and recall

When the host saves its project, the plugin’s persisted state goes into the project file. That state captures:

• the absolute path to the loaded .patches file
• the DSL source itself (stored verbatim, so the project survives a missing or moved file)
• host-control values
• per-tap display options (scope decimation, spectrum FFT size, etc.)
• the GUI window size
• the user’s persisted bundle-dir list

Reopening the project restores all of it. If the original file path no longer resolves, the plugin falls back to the embedded DSL source — the patch still plays; Browse re-points it at a live file.

The persisted-settings format is local to the plugin, so a project moved to another machine keeps its audio behaviour even if the file path doesn’t transfer.

GUI tour

• Header strip — current patch path, plus Browse… and Reload buttons.
• Modules tab — list of registered modules with an intent bar carrying Rescan (re-probe the bundle directories for FFI module bundles, used after dropping in a new .dylib) and Add bundle dir… (add to the per-project module search path).
• Diagnostics tab — Event log with compile diagnostics, hot-reload events, rescan reports, halt notifications, plus the current diagnostics summary.
• Tap views (separate tabs when the patch declares scope / meter / spectrum taps) — per-tap panels render the live signal. Display options (decimation, FFT size, heatmap on/off) persist with the project.

The internals of the plugin — webview IPC, snapshot pushes, halt handling — live in CLAP plugin internals.

Self-contained patches

A self-contained patch generates its own notes. It uses the tracker, step-sequencer, or clock modules as the note source rather than reading MIDI from an external controller or a DAW. Load it in the player, the piece starts, and the patch is the composition.

This is the third of the three peer workflows. The DSL, modules, and engine are identical to the other two — the only difference is what drives the gate, trigger, and pitch ports of the voice modules.

How it works

External-MIDI patches typically begin with something like:

module kbd : PolyMidiToCv
kbd.voct    -> osc.voct
kbd.gate    -> env.gate
kbd.trigger -> env.trigger

A self-contained patch replaces that source with a sequencer, and wires the sequencer’s clocks and CV outputs into one or more voices:

module seq: MasterSequencer([voice_a]) {
    song: my_song,
    bpm: 120,
    rows_per_beat: 4,
    autostart: true
}
module pp: PatternPlayer([note, vel])

seq.clock[voice_a] -> pp.clock
pp.cv1[note]       -> voice.voct
pp.gate[note]      -> voice.gate
pp.trigger[note]   -> voice.trigger
pp.cv1[vel]        -> voice.velocity

The notes themselves live in song and pattern blocks at the top of the file. Their full syntax — pitch names, ties (~), continues (.), velocity rows, transitions (>), repeats (*N), play { ... } structure — is covered in the DSL reference under the tracker section.

Walkthrough — tracker_three_voices.patches

examples/tracker_three_voices.patches is a three-voice piece: bass, two leads, stereo delay and reverb. Run it:

patch_player examples/tracker_three_voices.patches

It plays itself. No MIDI connection needed. Ctrl-C to stop.

The structure, top to bottom:

1. song demo(bass, lead1, lead2) — declares three named voices and the patterns they play. Each pattern block defines a row of pitches and a row of velocities; ~ ties into the previous note, . continues the gate, *N repeats. play { ... } lists the patterns to chain together, with * N for repetition.
2. template voice(...) — a parameterised synth-voice template exposing voct, gate, trigger, velocity inputs and one audio output. Internally: oscillator, ADSR, VCA, filter, glide.
3. template sq_voice(...) — a square-wave variant for lead 2.
4. patch { ... } — the actual graph. Inside:
   • MasterSequencer consumes the song and produces a per-voice clock plus pattern data.
   • One PatternPlayer per voice unpacks the active pattern’s rows into CV / gate / trigger streams.
   • Each voice template instantiates with per-voice parameters (attack, decay, filter cutoff, glide).
   • StereoMixer(3) sums voices, panning leads left and right.
   • A delay send/return loop and a master reverb + limiter sit on the bus.

The bottom of the file is the same AudioOut the player chapter showed — the only difference is that audio reaching it was generated internally rather than triggered from outside.

Autostart vs. external clock

MasterSequencer accepts autostart: true (start playing when the patch loads) or false (wait for an external trigger). In the player, with autostart: true, the patch plays as soon as the file is loaded. In a DAW, you can wire the host’s transport into the sequencer’s start input for project-synchronised playback — see the sequencer entry in Sequencers & clocks.

Mixing the modes

Nothing prevents a single patch from doing both. A MasterSequencer can drive a backing voice while a PolyMidiToCv reads incoming MIDI into a lead voice — the engine doesn’t care where the gate edges come from. Self-contained vs. externally-driven is a property of how the patch is wired, not a mode the player has to be told about.

DSL basics

This chapter introduces the syntax for declaring modules, setting their parameters, and drawing cables between them. It assumes the concepts from Mental model — modules, ports, cables, signal kinds — and shows how to write them down.

For the complete grammar with every form, see the DSL reference. This chapter is the on-ramp; that is the lookup table.

The patch block

Every .patches file ends with exactly one patch { ... } block. It contains module declarations, connections, and (optionally) pattern/song/template/host-control blocks. Comments run from # to end of line; whitespace and blank lines don’t matter.

patch {
    module osc : Osc { frequency: 440Hz }
    module out : AudioOut

    osc.sine -> out.in
}

A 440 Hz sine to the soundcard. Save and run.

Modules

A module declaration gives an instance a name and a type:

module osc : Osc

• Name — your handle for the instance (osc). Used in connections, and used for identity-matching across hot-reloads: a module whose name and type are unchanged carries its state across a reload.
• Type — the module type as registered in the module registry (Osc, PolyAdsr, Svf, StereoMixer). Determines what ports the instance has.

The set of available types is the module reference.

Parameters

Most modules take parameters in braces after the type:

module osc : Osc { frequency: 440Hz }
module env : Adsr { attack: 0.005, decay: 0.1, sustain: 0.7, release: 0.3 }

Parameter values support several literal forms:

There is no seconds suffix. Time parameters take a bare float (attack: 0.005 is 5 ms). The s after a number means semitones, not seconds — 7s is “seven semitones above C0”, which is G0. The Hz/kHz/dB/s/c suffixes are parsed as part of the literal and converted at compile time, so frequency: 440Hz and frequency: 440.0 are not equivalent — the first means 440 hertz, the second means 440 V/oct (which is nonsense). Use the right unit.

Shape arguments

Some modules have a variable number of ports. The shape is set in parentheses before the parameter braces. Prefer a named alias list — it documents what each channel is for and lets you address the indexed ports by name everywhere they appear:

module mix : StereoMixer([drums, bass, lead]) {
    @drums: { level: 0.8, pan:  0.0 },
    @bass:  { level: 0.7, pan: -0.2 },
    @lead:  { level: 0.6, pan:  0.3 }
}
module dly : StereoDelay([short, long]) { delay_ms: 750, feedback: 0.4 }

The aliases become channel names: mix.in[drums], mix.in[bass], mix.in[lead]. A bare count (StereoMixer(3)) or the named-count form (StereoMixer(channels: 3)) work too — they fall back to numeric indices (mix.in[0], mix.in[1], …) — but the alias form reads better and survives reordering.

Indexed parameters

Per-channel parameters are written with a bracket index — using the alias declared on the shape:

module mix : StereoMixer([drums, bass, lead]) {
    level[drums]: 0.8, pan[drums]:  0.0,
    level[bass]:  0.7, pan[bass]:  -0.2,
    level[lead]:  0.6, pan[lead]:   0.3
}

Or, more concisely, with the at-block form that groups all fields for one channel:

module mix : StereoMixer([drums, bass, lead]) {
    @drums: { level: 0.8, pan:  0.0 },
    @bass:  { level: 0.7, pan: -0.2, send_a: 0.3 },
    @lead:  { level: 0.6, pan:  0.3, send_a: 0.3 }
}

Numeric at-blocks (@0: { ... }) work when you declared the shape with a bare count.

The colon after @N is optional. Channels not listed take the parameter defaults defined by the module.

Connections

A connection (cable) carries a signal from one output port to one input port:

osc.sine -> filt.in
filt.lowpass -> vca.in
env.out -> vca.cv
vca.out -> out.in

module.port on each side; an arrow -> between them.

Fan-out is free. An output can drive many inputs without an explicit “split” module — draw multiple cables from the same output:

lfo.sine -> osc.frequency_cv
lfo.sine -> filt.cutoff_cv

Fan-in is summed automatically. List multiple sources before the arrow and the expander synthesises a Sum (or PolySum / StereoSum, depending on cable kind) under the hood:

osc_a.sine, osc_b.sine -> out.in

When you want explicit level control per channel — sends, mute/solo, panning — declare a Mixer or StereoMixer and route into its indexed inputs instead.

Scaled cables

A cable can multiply its signal by a constant. Write the scale in square brackets between the dashes:

osc.sine    -[0.3]-> out.in        # attenuate
lfo.sine    -[-1.0]-> osc.voct      # invert
mod.out     -[0.03]-> osc.phase_mod # light FM
mix.out  -[-12dB]-> out.in          # attenuate by 12 dB

The scale can be a plain number or a unit literal (dB, Hz, etc., where it makes sense for the destination).

Range-mapped cables

For modulation depth that depends on the destination’s natural unit, use uni(lo, hi) (maps a [0, 1] source into [lo, hi]) or bi(lo, hi) (maps a [-1, 1] source into [lo, hi]):

lfo.sine -[bi(-1Hz, 1Hz)]-> osc.frequency_cv
env.out  -[uni(0Hz, 1kHz)]-> filt.cutoff_cv

See the DSL reference for the full semantics and the cases where range-mapping matters.

Indexed ports

Connect to a specific channel by its alias (declared on the module’s shape) or by numeric index. Aliases are the better default — they document what each cable is for and don’t break when channels are added or reordered.

module mix : StereoMixer([bass, lead1, lead2])

bass_v.audio  -> mix.in[bass]
lead1_v.audio -> mix.in[lead1]
lead2_v.audio -> mix.in[lead2]

Numeric indices still work for modules declared with a bare count (StereoMixer(3) gives you mix.in[0], mix.in[1], mix.in[2]) and are fine for throwaway sketches. Reach for aliases as soon as the patch has more than two channels or you find yourself counting.

A complete example

Detuned sawtooth pair through a filter to stereo out:

patch {
    module osc_a : Osc { frequency: 220Hz }
    module osc_b : Osc { frequency: 221Hz }
    module filt  : Lowpass { cutoff: 1.5kHz }
    module out   : AudioOut

    osc_a.sawtooth, osc_b.sawtooth -> filt.in
    filt.out -[0.3]-> out.in
}

Run it, then change 221Hz to 222Hz and save — the beating slows without restarting the audio.

What’s next

• Signal kinds and cable rules — what connects to what, and why.
• Templates and abstraction — building reusable named subgraphs.
• Poly and voice allocation — polyphony, voice counts, MIDI-to-CV.
• DSL reference — every syntax form, for lookup.

Signal kinds and cable rules

Every port has a kind: what flavour of signal it carries. The kind decides which cables can connect to it. The five kinds — Audio, CV, Gate, Trigger, Stereo — were introduced in Mental model. This chapter lays out the rules the planner enforces and the conversions that happen for you.

The five kinds, quickly recapped

Underneath, the engine just streams f32 samples — there is no runtime tag distinguishing audio from gate. The kind is a typing discipline. Patches modules declare their ports’ kinds and the planner refuses connections that violate the rules.

The freedom of “samples are samples” is intentional: you can deliberately feed audio into a CV input for aggressive modulation, or run an envelope’s output through AudioOut as a one-shot percussion sample. The type system lets the planner catch the mistakes worth catching while leaving the creative misuse paths open.

Mono and poly are orthogonal

A cable is also either mono (one sample per audio tick) or poly (one sample per voice per tick — typically 16 voices). This is independent of the kind:

• Osc (mono) has mono audio outputs.
• PolyOsc (polyphonic) has poly audio outputs.
• Similarly Adsr (mono CV out) and PolyAdsr (poly CV out).

A module instance is wholly mono or wholly poly; there is no “mostly mono with one poly port” mixed case. The poly counterpart of a mono module type is a separate type, usually prefixed Poly.

Cable rules

The planner enforces the following rules at compile time:

Identical kind → free

Audio→Audio, CV→CV, Gate→Gate, Trigger→Trigger, Stereo→Stereo all connect without ceremony.

osc.sine    -> filt.in       # Audio → Audio
lfo.sine    -> osc.voct      # CV    → CV
midi.gate   -> env.gate      # Gate  → Gate
midi.trigger -> env.trigger  # Trigger → Trigger

Audio ↔ CV / Gate / Trigger → free

Because they are all f32 streams under the hood, mono Audio / CV / Gate / Trigger can be cross-connected. The planner does not flag this — it’s the deliberate-misuse path.

This is a feature: routing an envelope’s output as audio gives a one-shot percussion sample; routing an audio signal into a CV input gives audio-rate modulation.

Mono Audio → Stereo input → silent broadcast

A mono audio output feeding a stereo audio input is silently broadcast: L = R = source. No synthetic splitter node, no warning.

osc.sine -> dly.in           # dly.in is stereo; sine is mono
                             # → both channels receive sine

This removes the need for explicit broadcasters at every mono-to-stereo boundary.

Stereo → mono input → rejected

The reverse is not permitted. Compiling fails with CableKindMismatch. If you want to mix down, route through PolyToMono for poly, or StereoSplitter / StereoJoiner for stereo when you want both halves explicitly.

dly.out -> mono_filt.in      # ERROR: stereo → mono

Use StereoSplitter first if the split is intentional:

module split : StereoSplitter
dly.out      -> split.in
split.left   -> mono_filt.in

Mono ↔ Poly → bridge module required

Mono and poly are not auto-convertible. Use MonoToPoly to broadcast a mono signal to every voice:

module mtp : MonoToPoly
lfo.sine -> mtp.in
mtp.out  -> poly_osc.voct    # poly_osc.voct now sees the LFO on all voices

And PolyToMono to sum poly voices into a single mono stream:

module ptm : PolyToMono
poly_vca.out -> ptm.in
ptm.out      -> reverb.in

There is no automatic broadcast or sum; the type mismatch must be handled by an explicit module so it appears in the patch.

Fan-out and fan-in

Two separate rules, distinct from kind rules:

• Fan-out is free. An output port can drive any number of inputs. Draw multiple cables from it; no “split” module needed.
• Fan-in needs a mixer. An input port accepts exactly one cable. To combine signals into one input, route them through a Sum, Mixer, StereoMixer, or similar.

# Fan-out: one LFO modulates three destinations
lfo.sine -> osc.frequency_cv
lfo.sine -> filt.cutoff_cv
lfo.sine -> vca.cv

# Fan-in: three sources sum into one filter — auto-summed,
# no explicit Sum module needed
osc_a.sine, osc_b.sine, osc_c.sine -> filt.in

Cable delay

This is a subtle one and matters for understanding when feedback is well-defined.

In a cycle-bearing region of the graph, every cable carries a one-sample delay: a module’s process call sees what its neighbours wrote on the previous tick. This is what makes feedback loops have a well-defined value at every tick — a feedback cable is simply yesterday’s sample.

In acyclic (feedback-free) regions, the planner fuses the chain so consumers read producers’ current-tick output. This is invisible to you — the audio matches the conceptual model — but it removes the one-sample-per-cable lag that would otherwise accumulate audibly across a long signal chain.

You don’t need to think about this when writing a patch. The cable delay matters only when you’re building feedback loops where the one-sample latency is a feature (a delay line’s feedback path, a self-oscillating filter, a phase-modulation loop).

Summary

If a connection is rejected, the diagnostic will name the source kind, the destination kind, and the rule that fails. Read it literally — it tells you which bridge module to insert.

Templates and abstraction

A template is a named, parameterised subgraph that you can stamp out many times in a patch. Templates are expanded at compile time — they are a DSL-level abstraction, not a runtime construct. Every instantiation produces concrete module instances with mangled names, and the result is what the engine actually runs.

Use templates to:

• Define a synth voice once and instantiate it per pitch / role.
• Wrap a stable subgraph (an effect chain, a stereo widener, a drum kit channel) so the top-level patch reads at a higher level of abstraction.
• Parameterise across patches — a voice template lives in one place and a hundred patches can use it.

Defining a template

A template definition is a top-level block:

template voice(attack: float = 0.01, decay: float = 0.1,
               sustain: float = 0.7, release: float = 0.3) {
    in:  voct, gate, trigger
    out: audio

    module osc : Osc
    module env : Adsr { attack: <attack>, decay: <decay>,
                        sustain: <sustain>, release: <release> }
    module vca : Vca

    $.voct    -> osc.voct
    $.gate    -> env.gate
    $.trigger -> env.trigger

    osc.sawtooth -> vca.in
    env.out      -> vca.cv
    vca.out      -> $.audio
}

Three things to notice:

1. Parameter list (attack: float = 0.01, ...). Typed, with optional defaults. Types are float, int, bool, str, pattern, song. Parameters without a default are required at the call site.
2. Boundary ports (in: and out: lists). These are the template’s external interface. Inside the body, $.name refers to the boundary port name.
3. Parameter references (<attack>). Substituted wherever a value is expected in the body: parameter values, scale factors, shape arguments. The substitution happens during expansion, so attack: <attack> becomes attack: 0.01 in the expanded copy.

The body is otherwise just patch syntax — modules, connections, scaled cables. Templates can also use the <- backward arrow, which makes destination-first writing cleaner for out: ports:

$.audio <- vca.out

is equivalent to vca.out -> $.audio.

Instantiating

A template instantiates with the same module name : Type syntax as a built-in module, except the type is the template name and the parentheses carry the template arguments:

patch {
    module bass_v  : voice(attack: 0.005, decay: 0.15, sustain: 0.6)
    module lead1_v : voice(attack: 0.02,  decay: 0.3,  sustain: 0.5)
    module lead2_v : voice    # all defaults
    module mix     : StereoMixer([bass, lead1, lead2])

    bass_v.audio  -> mix.in[bass]
    lead1_v.audio -> mix.in[lead1]
    lead2_v.audio -> mix.in[lead2]
}

Each instantiation expands to its own copy of the template’s modules; the engine sees bass_v_osc, bass_v_env, bass_v_vca, lead1_v_osc, and so on as distinct instances. From outside, an instance presents only its declared boundary ports — bass_v.voct, bass_v.gate, bass_v.audio. The internals are invisible.

Parameter types

Type checking is strict — a float parameter rejects true; a bool rejects 0. The error message names the parameter and the expected type.

Arity parameters

A template can take a parameter that controls the number of ports. Inside the body, [*name] expands per-index:

template summing_voice(size: int, level[size]: float = 1.0) {
    in:  audio[size]
    out: mixed

    module sum : Sum(<size>)

    $.audio[*size] -> sum.in[*size]
    sum.out        -> $.mixed
}

Instantiate it with a concrete size, and the connection $.audio[*size] -> sum.in[*size] expands into one cable per index: $.audio[0] -> sum.in[0], $.audio[1] -> sum.in[1], and so on. The level[size] indexed parameter accepts per-index values: level[0]: 0.8, level[1]: 0.6, ....

Scale composition across boundaries

When a scaled connection crosses a template boundary, the scales multiply. A patch-level -[0.5]-> into a template that internally attenuates with -[0.3]-> produces an effective scale of 0.15 at the underlying cable — there is no intermediate buffer.

# Inside the template:
module mix : Sum(2)
$.in -[0.3]-> mix.in[0]
...

# In the patch:
src.out -[0.5]-> tmpl.in
# Effective scale at sum.in[0]: 0.5 * 0.3 = 0.15

This means template authors don’t need to leave headroom for “unknown caller scaling” — the multiplication composes predictably.

Nesting

Templates can instantiate other templates. The expander flattens the whole tree before the patch is built:

template filtered_voice(...) {
    in: voct, gate, trigger
    out: audio

    module v : voice(attack: 0.005, ...)
    module f : Lowpass { cutoff: 1.2kHz }

    $.voct    -> v.voct
    $.gate    -> v.gate
    $.trigger -> v.trigger
    v.audio   -> f.in
    f.out     -> $.audio
}

patch { module fv : filtered_voice; ... } expands to a v_voice sub-instance, a v_voice_osc, v_voice_env, v_voice_vca, and a v_filter — six concrete instances from one declaration. Recursion is bounded by depth; infinite recursion is caught at expansion time with a clear error.

When to use templates

Use them when:

• The same subgraph appears three or more times.
• A subgraph has a stable interface (a few clearly-named boundary ports) and you want to vary internal parameters.
• You want to name an abstraction (voice, kit_channel, widener) that makes the top-level patch read at a higher level.

Skip them when:

• A subgraph appears once and won’t be reused. Inline modules read better than a one-shot template.
• You’re tempted to use templates to abstract over module types. Templates instantiate a fixed set of modules with parameterised values — they don’t let you swap Osc for PolyOsc. For that, write two templates.

Templates as facades

A useful mental model: a template is a typed facade over the underlying graph. The parameter list declares which knobs are exposed; the port list declares the connection surface. The body — which modules get instantiated and how they’re wired — is hidden implementation. Patches that use the template see only the typed interface; the expander erases the abstraction before the engine ever runs.

This is why scale composition, port-arity expansion, and parameter substitution all happen at expansion time: templates are a compile step, not a runtime layer.

Poly and voice allocation

A poly cable carries one sample per voice per audio tick, where “voice” is one of a fixed-size pool. Patches uses a pool size of 16 voices in every shipping host (player, CLAP plugin, integration tests). A poly cable’s data is laid out as 16 parallel mono streams.

This chapter covers how poly works at the patch level: how to introduce voices, how MIDI gets mapped into them, what happens when the pool fills up, and how to bridge between mono and poly.

Poly module types

Most module types come in mono-only flavour. Poly variants exist for the building blocks of a polyphonic voice:

A poly module’s ports are poly throughout: PolyOsc.voct is a poly CV input that takes one V/oct value per voice, and its sawtooth output is a poly audio stream of 16 sawtooths. An entire voice — oscillator, envelope, filter, VCA — is wired in poly and produces 16 parallel voice outputs, which are then mixed down to a mono or stereo signal for the master bus.

Voice allocation: PolyMidiToCv

The standard way to introduce poly is with PolyMidiToCv. It receives MIDI note-on / note-off events and assigns each note to a voice slot, exposing per-voice voct, gate, trigger, and velocity poly outputs.

module kbd : PolyMidiToCv
module osc : PolyOsc
module env : PolyAdsr {
    attack: 0.005, decay: 0.1, sustain: 0.7, release: 0.3
}
module vca : PolyVca
module mix : PolyToMono
module out : AudioOut

kbd.voct    -> osc.voct
kbd.gate    -> env.gate
kbd.trigger -> env.trigger

osc.sine -> vca.in
env.out  -> vca.cv
vca.out  -> mix.in
mix.out -[0.2]-> out.in

The signal chain is wholly poly from kbd through vca; PolyToMono sums the 16 voices into one mono stream before output.

Allocation policy

When a new note arrives:

1. A free voice exists. The note takes the first free slot.
2. All voices are active. The most-recently-allocated voice is stolen (LIFO — last in, first out): its gate goes low briefly, then the new note takes its slot.

This is fast, predictable, and avoids the “oldest voice dropping mid-release” surprise of FIFO stealing. The trade-off: rapidly restruck notes can chain-steal each other if you exceed 16 simultaneous voices.

Note-off releases the matching voice, gating its envelope down. The voice slot becomes free for reuse after the envelope’s release phase finishes (or immediately, if a new note steals it).

Velocity

PolyMidiToCv.velocity carries the per-voice velocity as a CV signal (0 to 1). Route it into a PolyVca’s CV input to velocity-shape the envelope:

module vel_vca : PolyVca
env.out      -> vca.cv
vca.out      -> vel_vca.in
kbd.velocity -> vel_vca.cv
vel_vca.out  -> mix.in

Bridges: MonoToPoly / PolyToMono

Mono and poly cables cannot connect directly. Two bridge modules handle the boundary.

MonoToPoly — broadcast

MonoToPoly copies a mono signal to every voice. Useful when a single LFO or envelope modulates all voices identically:

module lfo : Lfo { rate: 0.5 }
module mtp : MonoToPoly

lfo.sine -> mtp.in
mtp.out  -> poly_osc.frequency_cv   # All voices receive the same LFO

After MonoToPoly, every poly voice slot carries the source’s sample value.

PolyToMono — sum

PolyToMono sums the active voices into a single mono stream. This is the standard way to take a poly voice chain to the master bus:

module ptm : PolyToMono
poly_vca.out -> ptm.in
ptm.out      -> reverb.in

PolyToMono only sums the active voices. Inactive slots contribute zero — there’s no per-voice CPU overhead for unused voices in the mix-down, though every poly module still runs all 16 slots per tick.

Where poly costs come from

Poly modules run all 16 voice slots every tick. A PolyOsc is, at runtime, 16 oscillator instances running in parallel — but they share state allocation, control-rate updates, and DSP kernel calls, so the per-voice overhead is much lower than 16 separate Osc instances would be.

In practice:

• Poly voice chains scale linearly with module count in the chain, not with active voice count.
• Mono modules between poly nodes (e.g. a global reverb fed by PolyToMono) cost the same regardless of how many voices are playing.
• Effects you want per-voice (chorus, drive, voice-specific filter) go inside the poly chain; effects on the global sound go after the mix-down.

Mixing mono and poly

There’s no rule against using a mono MidiToCv for a lead voice and a PolyMidiToCv for a pad in the same patch — the engine doesn’t care. The same physical MIDI input feeds both modules; each does its own allocation.

module lead : MidiToCv         # mono — monophonic lead
module pad  : PolyMidiToCv     # 16-voice pad

This is the typical structure for a hybrid synth: a mono lead voice with its own dedicated note source, plus a poly pad voice running in parallel. Both modules see the same MIDI traffic.

What’s next

PolyMidiToCv is the most common source of poly traffic, but other modules also produce poly streams — sequencers with multiple voice outputs, drum-rack patterns, modulation matrices. See the Sequencers & clocks and MIDI reference pages for the full set.

DSL reference

This is the complete syntax reference for .patches files. It assumes familiarity with the concepts in Mental model and the narrative introductions in DSL basics, Signal kinds and cable rules, Templates and abstraction, and Poly and voice allocation. This page is the lookup; those are the on-ramp.

File structure

A patch file contains zero or more top-level blocks followed by exactly one patch block. Comments run from # to end of line. Whitespace is insignificant.

# optional: include another .patches file (templates / patterns / sections)
include "shared/voices.patches"

# optional: pattern definitions for the tracker sequencer
pattern kick_basic {
    hit: x:1.0 . . . x:1.0 . . .
}

# optional: song definitions referencing patterns
song my_song(kick, bass) {
    play {
        kick_basic, bass_verse
    }
}

# optional: top-level reusable section (visible to all songs)
section intro {
    kick_basic, bass_verse
}

# optional: templates
template voice(...) {
    ...
}

# required: exactly one patch block
patch {
    ...
}

include directive

include "path" inlines another .patches file at the point of the directive. Includes are resolved at parse time, relative to the including file. The included file may contribute templates, patterns, songs, and top-level sections — but not a patch block (only the root file declares one).

Module declarations

module <name> : <Type>
module <name> : <Type> { <params> }
module <name> : <Type>(<shape-args>) { <params> }
stereo module <name> : <Type>(<shape-args>) { <params> }

• name — an identifier ([a-zA-Z_][a-zA-Z0-9_-]*). Used for connections and for identity matching across hot-reloads.
• Type — the module type name as registered in the module registry (e.g. Osc, PolyAdsr, Sum).
• shape-args — key-value pairs that control port arity. Written in parentheses before the parameter braces: Sum(channels: 3).
• params — key-value pairs configuring the module’s parameters.
• stereo — prefix keyword requesting two parallel instances of the module sharing connections and parameters. Per-side overrides use @l: / @r: at-blocks; per-side ports are addressed via port[l] / port[r].

Parameter syntax

Parameters are comma-separated key: value pairs:

module env : Adsr { attack: 0.01, decay: 0.1, sustain: 0.8, release: 0.3 }

Indexed parameters use bracket notation:

module mix : StereoMixer(channels: 4) { level[0]: 0.8, pan[0]: -0.5 }

At-block syntax groups parameters by index:

module dly : Delay(channels: 2) {
    @0: { delay_ms: 250, feedback: 0.4 },
    @1: { delay_ms: 375, feedback: 0.3 }
}

When the module shape defines named aliases, those can be used instead of numeric indices:

module mix : Mixer(channels: [drums, bass, lead]) {
    @drums { level: 0.8 },
    @bass  { level: 0.6 }
}

On a stereo module, the special @l: / @r: blocks override per side:

stereo module dly : Delay(channels: 2) {
    @0: { delay_ms: 250 },
    @l: { feedback: 0.45 },   # left-side-only override
    @r: { feedback: 0.55 }    # right-side-only override
}

Parameter value types

Frequency, note, and dB literals are case-insensitive. There is no time-unit suffix; durations are bare floats in seconds. s after a number means semitones, not seconds.

Connections

Forward connection

osc.sine -> out.in

out here is AudioOut, whose in is a stereo port. The mono osc.sine broadcasts onto both channels automatically (see Cable kinds below).

Scaled forward connection

osc.sine -[0.5]-> out.in

The scale factor is a float multiplied onto the signal at the cable level.

Range-mapped connections

A scalar -[k]-> only multiplies the signal. To map a known source range affinely onto a destination range, use a range expression on the arrow:

ctrl.knob -[uni(20Hz, 8kHz)]-> filter.cutoff
lfo.out   -[bi(C2, C5)]->      osc.voct

Both forms hard-clip at the destination endpoints; out-of-source-range inputs saturate.

uni(lo, hi) — [0, 1] → [lo, hi]

For knob and host-control sources delivering a normalized value:

patch {
    knob   cutoff { displayName: "Cutoff" }
    module filt : Svf

    ~cutoff -[uni(20Hz, 8kHz)]-> filt.cutoff
}

bi(lo, hi) — [-1, 1] → [lo, hi]

For bipolar modulation sources (LFOs, audio-rate modulators):

patch {
    module lfo : Lfo
    module osc : Osc

    # vibrato around C4, ±1 octave; note literals lower to v/oct.
    lfo.sine -[bi(C3, C5)]-> osc.voct
}

Note literals and Hz / kHz literals mix freely inside a single range — both belong to the pitch family and lower to v/oct over C0. Other unit families (s, dB) stay in their native unit. Cross-family pairs are rejected at expansion time:

# error: cable range endpoints have incompatible unit families:
#        pitch vs level
osc.sine -[bi(440Hz, -12dB)]-> dst.in

Endpoints accept the same forms as scalar scales: numeric and unit-suffixed literals, note literals, and <param> references. A template can therefore parameterise the destination range:

template knob_to_cutoff(lo: float, hi: float) {
    in: knob
    out: cutoff
    $.knob -[uni(<lo>, <hi>)]-> $.cutoff
}

Range and scalar segments compose freely across template boundaries (see Scale composition below); the result is a single affine plus clip applied once at the destination port.

Backward connection

$.audio <- vca.out
$.audio <-[0.5]- vca.out

<- connects from right to left. Primarily useful inside templates for wiring boundary ports. The scaled form uses <-[scale]-.

Indexed ports

The index in brackets selects which slot of a multi-port to connect. Aliases declared on the module’s shape are the idiomatic form:

module mix : Mixer([drums, bass, lead])

kick.out -> mix.in[drums]
bass.out -> mix.in[bass]
lead.out -> mix.in[lead]

Numeric indices work when the shape is declared as a bare count:

module sum : Sum(2)

osc_a.sine -> sum.in[0]
osc_b.sine -> sum.in[1]

On stereo modules, the channel selectors [l] and [r] address the per-side instance instead of a numeric index:

stereo module dly : Delay
src.left  -> dly.in[l]
src.right -> dly.in[r]

Fan-in and fan-out

A comma-separated list of endpoints on either side of an arrow connects multiple sources or destinations in one statement:

osc.sine -> filter.in, scope.in            # fan-out: one source → many sinks
voice_a.out, voice_b.out -> mix.in         # fan-in: many sources → one sink

Fan-out drives every listed sink from the same source. Fan-in to a single input port of uniform cable kind is auto-summed: the expander synthesises a Sum (or PolySum / StereoSum) module under the hood. Mixed-kind fan-in is rejected at expansion time.

Arity expansion

$.audio[*size] -> sum.in[*size]

The [*name] wildcard expands into one connection per index from 0 to name - 1. Only valid inside templates where name is an int parameter.

Rules

• An input port may receive multiple connections of uniform cable kind; the expander synthesises a Sum / PolySum / StereoSum to combine them (see Fan-in and fan-out). Mixed-kind fan-in is rejected.
• An output port can drive any number of inputs.
• Cable kinds must match: mono ↔ mono, poly ↔ poly, stereo ↔ stereo. Use MonoToPoly / PolyToMono to bridge mono and poly.

Cable kinds (mono / poly / stereo)

• Mono carries one f32 per tick. The default for control and audio cables.
• Poly carries 16 voices ([f32; 16]). Used by Poly* modules.
• Stereo carries an (L, R) pair. Stereo modules expose a single port — stereo_delay.in, lim.out — instead of paired *_left / *_right ports.

A mono Audio source feeding a stereo input is silently broadcast (L = R = source); no extra wiring is needed for the common “mono-into-effect” case. Stereo→mono is rejected — when the user genuinely wants the two halves apart they go through StereoSplitter, and StereoJoiner assembles two monos back into one stereo cable.

Host controls

A host control is a named source surfaced to the plugin host (CLAP parameter, knob row in the CLI). Four kinds, declared at the top of patch { ... }:

patch {
    knob    cutoff   { displayName: "Cutoff" }
    slider  mix      { default: 0.5 }
    toggle  bypass   { default: false }
    trigger fire     { }
}

• knob / slider produce a smoothed audio-rate signal in [-1, 1].
• toggle produces a stepped 0 / 1 signal; default is required.
• trigger produces one-sample pulses fired by the host; no required fields.

Fields

References

A ~name reference on a cable endpoint connects the host control to a port:

patch {
    knob cutoff { }
    module filt : Svf
    ~cutoff -[uni(20Hz, 8kHz)]-> filt.cutoff
}

The cable carries the normalized [-1, 1] value; the range operator remaps it to the destination’s musical units.

Implicit knob

If a ~name cable endpoint has no matching declaration, the desugarer synthesises an empty knob name {} block:

patch {
    module filt : Svf
    ~cutoff -[uni(20Hz, 8kHz)]-> filt.cutoff   # implicit knob `cutoff`
}

Implicit and explicit empty-knob forms lower to the same patch. To surface a slider, toggle, or trigger instead, declare it explicitly — only knob is implicit.

Templates

Templates define reusable sub-graphs that are expanded at compile time with no runtime cost.

Definition

template voice(attack: float = 0.01, decay: float = 0.1, sustain: float = 0.7) {
    in:  voct, gate
    out: audio

    module osc : Osc
    module env : Adsr { attack: <attack>, decay: <decay>, sustain: <sustain>, release: 0.3 }
    module vca : Vca

    $.voct    -> osc.voct
    $.gate    -> env.gate
    osc.sine  -> vca.in
    env.out   -> vca.cv
    $.audio   <- vca.out
}

• Parameters are typed: float, int, str, bool, pattern, song. Parameters with = default are optional at the call site; those without are required.
• Boundary ports are declared with in: and out: lists. Inside the template body, $.name refers to a boundary port.
• Parameter references <name> substitute the parameter’s value anywhere in the template body: in parameter values ({ attack: <attack> }), port names (osc.<wave>), and cable scales (-[<gain>]->).

Instantiation

patch {
    module v1 : voice(attack: 0.005, sustain: 0.6)
    module v2 : voice    # all defaults

    v1.audio -> out.in
    v2.audio -> out.in
}

Each instantiation expands to a separate copy of the template’s modules with mangled names to avoid collisions.

Parameter types

Type checking is strict. A float parameter rejects true; a bool rejects 0.

Arity parameters

A template parameter can control the number of ports:

template mixer(size: int, level[size]: float = 1.0) {
    in: audio[size]
    out: mixed

    module sum : Sum(channels: <size>)

    $.audio[*size] -> sum.in[*size]
    $.mixed        <- sum.out
}

The [*size] expansion generates one connection per index, scaling automatically with the arity.

Scale composition

When a scaled connection crosses a template boundary, the scales are multiplied. A connection -[0.5]-> into a template that internally has -[0.3]-> produces an effective scale of 0.15 at the underlying cable.

Nesting

Templates can instantiate other templates. A filtered_voice template can contain module v : voice(...) and add further processing. Expansion is recursive — the outermost template is fully flattened before the patch is built.

Patterns

Pattern blocks define step data for the tracker sequencer. Each pattern has one or more named channels, and each channel has a row of step values.

pattern bass_line {
    note: C2  .  Eb2 .  G1  .  Ab1 .
    vel:  1.0 .  0.8 .  0.9 .  0.7 .
}

• Channel names (note, vel, hit, etc.) are identifiers. They must match the channels list on the PatternPlayer that reads this pattern.
• All channels in a pattern must have the same number of steps.
• Steps are separated by whitespace.

Step events

The step grammar is a unified taxonomy of cell shapes (ADR 0077). Each cell of a channel row parses into one shape; the row-build pass walks each channel left-to-right tracking (slide_open, roll_active) channel state and emits a resolved effect per cell. The pattern player dispatches on the resolved effect.

Cell taxonomy

A cell produces up to four signals: cv1, cv2, trigger, gate.

value is any of: note name (C4, A#3), float (0.5), int (2), unit literal (440Hz, -6dB). The optional :cv2 tail attaches to value, value>, /value, and >value (cv2 endpoints on close cells ramp through the slide). Cv2 on value>value sugar is A:0.5>B:0.8.

Unified close rule

A slide opened by value> or >_ closes when the row-build pass encounters a non-_, non->_, non-value> cell:

• value close — slide lands at value at the tick boundary entering the cell; cell then fires a fresh trigger on its own tick.
• /value close — slide lands at value at the tick boundary; cell holds without retrigger.
• >value close — slide ramps to value inside this tick (no trigger); the close-tick is itself a slide-flow tick.

The lead-in shape (flat hold vs ramp) is determined by prior cells, not by anything on the close cell. Bare value is therefore always locally readable as a fresh trigger.

Continuation absorption

A _ cell takes its meaning from whichever modifier was last open on the channel:

• After a non-roll, non-slide anchor: sustain (gate held, cv unchanged).
• After a value*N anchor: absorbed into the roll’s spread schedule (the N sub-triggers spread across the anchor tick + the absorbed-tie run). Span S = 1 + consecutive_underscores; sub-triggers fall at k * S / N of the span for k = 0..N-1; gate articulates at ~80% of each interval. Swing within the span is respected per-tick.
• After a value> or >_: absorbed into the slide’s ramp.

>_ is the explicit-flow form for slides that start on a non-value cell (“hold this note for a bit, then start ramping”).

Worked-example timelines

Each five-tick figure below shows trigger placement (!), gate articulation (- = high, . = low), and cv shape across ticks.

Pattern:  E4 . . . .
Tick:     1  2  3  4  5
Trigger:  !  .  .  .  .
Gate:     -- .  .  .  .
cv1:      E4 E4 E4 E4 E4   (held after gate drops; analog convention)

Pattern:  E4 /G4 . . .
Tick:     1   2  3  4  5
Trigger:  !   .  .  .  .   (only the E4 fires)
Gate:     --- -- .  .  .
cv1:      E4  G4 G4 G4 G4  (snap at the 1→2 boundary)

Pattern:  E4 _ /G4 . .
Tick:     1  2  3  4  5
Trigger:  !  .  .  .  .
Gate:     -- -- -- .  .
cv1:      E4 E4 G4 G4 G4  (snap at the 2→3 boundary)

Pattern:  E4> _ G4 . .
Tick:     1   2  3  4  5
Trigger:  !   .  !  .  .   (fresh G4 trigger at start of tick 3)
Gate:     --- -- -- .  .
cv1:      E4→ →G4 G4 G4 G4 (ramp through ticks 1+2; lands at boundary)

Pattern:  E4 _ >_ /G4 .
Tick:     1  2  3  4  5
Trigger:  !  .  .  .  .
Gate:     -- -- -- -- .
cv1:      E4 E4 E4→ G4 G4   (slide opens at tick 3 via >_; closes at
                              tick-3→tick-4 boundary)

Pattern:  E4> _ >G4 . .
Tick:     1   2  3   4  5
Trigger:  !   .  .   .  .
Gate:     --- -- --- .  .
cv1:      E4→ →  →G4 G4 G4  (continuous ramp across ticks 1-3; lands
                              at end of tick 3)

Pattern:  x*3 _ . . .
Tick:     1   2 3 4 5
Trigger:  !!!!! . . . .     (3 sub-triggers spread across ticks 1+2,
                              `*0/3`, `*2/3`, `*4/3` of T each)
Gate:     -..-..-.. . . .   (~80% duty per sub-interval)
cv1:      anchor cv1 held across the span

The value>value sugar is the common one-tick case: it packs an open-and-close into a single cell. It is exactly equivalent in effect to value> /value except that the unsugared form takes two ticks (slide tick 1, hold tick 2). Use the sugar when the timing fits.

Row-continuation across |

Channel state and slide / roll spans flow through the | row-continuation marker — the parser merges continuations into one logical row before the row-build pass, so a span can cross the join:

hit: x*3
   | _ _
vox: A3>
   | _ /B3

Migration from ~

The ~ tie token was retired in favour of _ (ADR 0077). Old patches using ~ in step rows do not parse; mechanically replace ~ → _ inside pattern bodies. The cable-endpoint forms (~tap(…), ~host_control) are unaffected.

slide(…) macro retired

The slide(n, A, B) macro generator was removed in ticket 0948. Authors write slides inline using the cell shapes above. Mechanical equivalences:

• slide(1, A, B) → A>B
• slide(2, A, B) → A> >B
• slide(n, A, B) (n ≥ 3) → A> + (n−2)×>_ + >B

Known limitations

• Row-end truncation: a slide or roll never extends past the end of a channel row. x*5 _ _ at the end of a 3-step row still fires 5 sub-triggers across those 3 ticks. A value> with no close cell in the row is degraded to a no-op (close target = open value); the row-build pass emits a diagnostic.
• Cross-loop / cross-bank: spans don’t wrap past a pattern loop or bank boundary; trailing sub-events are dropped rather than wrapping.
• Mid-span live edit: if a _ cell is edited to a non-tie mid-roll or mid-slide, the new content takes over on its own tick rise and the prior span is replaced (no overrun).

Songs

A song block defines a playback order built from named section blocks and play statements.

song my_song(bass, lead, drums) {
    section verse {
        bass_verse, lead_verse, drums_a
        bass_verse, lead_verse, drums_b
    }
    section chorus {
        bass_chor, lead_chor, drums_a
    }

    play verse
    @loop
    play (verse, chorus) * 2
}

Lanes

The lanes — the identifiers in parentheses after the song name — declare one column per pattern assignment. Every row must supply exactly this many cells. Lane names must match the channels shape argument on the MasterSequencer.

Cells

A row is a comma-separated list of cells. A cell is one of:

• a pattern name — the pattern played in that lane for that row;
• _ — silence on that lane;
• <param> — a template-parameter reference, resolved at expansion time.

Rows are separated by newlines (newlines are significant inside row sequences). A parenthesised sub-sequence can be repeated: (a, b c, d) * 2. A bare cell * N (without parentheses) is rejected at parse time.

Sections

A section block is a named, reusable row sequence. Sections may be defined inside a song (song-local scope) or at file top level (visible to all songs). A section has no lane count of its own; it is validated against the invoking song’s lanes when play references it.

Play statements

play composes sections into the song’s running row list:

• play verse — append verse.
• play verse, chorus — append verse, then chorus.
• play chorus * 2 — append chorus twice (* binds tighter than ,).
• play (verse, chorus) * 4 — append the group four times.
• play { row, ... } — an anonymous inline body (no section name).
• play chorus { row, ... } — defines chorus as a song-local section and plays it once. Later play chorus / chorus references replay it.

Inline bodies (play { ... } and play name { ... }) appear only as the entire body of a single play statement. They cannot be mixed into a composition expression such as play a, { row, ... }, b.

Loop marker

@loop is a standalone song item between play statements. It sets the loop-back row index in the emitted song. A song may contain at most one @loop; omitting it loops the song from the beginning.

Inline patterns

pattern blocks may appear as song items alongside section and play. Inline patterns are song-local: their names are mangled under the enclosing song so two songs may each define a fill pattern without collision.

Anatomy of a synth voice

This chapter walks through examples/synths/lead.patches, a sixteen-voice polyphonic lead synth driven by MIDI. It’s the canonical “build a synth voice from oscillator outward” patch. The architecture generalises: pad, bass, pluck, brass — every voice in examples/synths/ is a variation on the same skeleton with different envelope and filter choices.

This is patch authoring, not DSL syntax. If you want a refresher on how module declarations and connections work, read DSL basics first.

The full patch

patch {
    module kbd      : PolyMidiToCv
    module osc      : PolyOsc { drift: 0.04 }
    module mix      : PolySum([saw, sq])
    module amp_env  : PolyAdsr {
        attack: 0.003, decay: 0.18, sustain: 0.7, release: 0.18
    }
    module vca      : PolyVca
    module filt_env : PolyAdsr {
        attack: 0.005, decay: 0.22, sustain: 0.4, release: 0.2
    }
    module filt     : PolyLowpass {
        cutoff: 1.2kHz, resonance: 0.55, saturate: true
    }
    module delay    : StereoDelay {
        delay_ms: 280, feedback: 0.35, tone: 0.7, dry_wet: 0.25,
        pingpong: true
    }
    module lim      : StereoLimiter { threshold: -3db }
    module out      : AudioOut

    kbd.voct        -> osc.voct
    kbd.trigger     -> amp_env.trigger
    kbd.gate        -> amp_env.gate
    kbd.trigger     -> filt_env.trigger
    kbd.gate        -> filt_env.gate

    osc.sawtooth -[0.6]-> mix.in[saw]
    osc.square   -[0.5]-> mix.in[sq]
    mix.out         -> vca.in
    amp_env.out     -> vca.cv

    vca.out         -> filt.in
    filt_env.out -[1.0]-> filt.voct

    filt.out     -[0.1]-> delay.in
    delay.out       -> lim.in
    lim.out         -> out.in
}

Load it as a CLAP plugin on a MIDI track (or via patch_player with a connected MIDI controller). Play. The rest of this chapter is the explanation.

Signal flow

A classic subtractive architecture: oscillator → mixer → amplifier → filter → effects → output. Every stage from osc through filt is polyphonic, so each of the 16 voices has its own independent signal path. After the filter, the StereoDelay and StereoLimiter operate on a stereo bus — they don’t need to be per-voice.

kbd ──voct────→ osc ──saw────→ mix ──→ vca ──→ filt ──→ delay ──→ lim ──→ out
                      ──sq────↗        ↑       ↑
                                   amp_env  filt_env

The mono-to-stereo step happens implicitly at filt.out -> delay.in: delay.in is a stereo input, and a mono audio source into a stereo input silently broadcasts to both channels. No explicit MonoToStereo needed.

MIDI input

PolyMidiToCv is the source of poly traffic for the whole patch. It receives MIDI events from the host (DAW or patch_player), allocates each note-on to a voice slot (LIFO stealing if all 16 are busy), and produces three poly outputs:

• voct — pitch as V/oct (1 unit per octave). Drives osc.voct.
• gate — 1.0 while a key is held, 0.0 when released. Tells the envelopes when to enter their release phase.
• trigger — single-sample pulse on note-on. Tells the envelopes when to restart from the attack phase.

The gate / trigger distinction matters. The gate tells the envelope how long the note is held; the trigger tells it when to restart. With only a gate, restriking the same note while the previous release is still falling wouldn’t retrigger — the gate would stay high through both presses.

For DAW use, the host writes its track’s MIDI directly to the plugin; you don’t think about device selection.

Oscillator and mixing

PolyOsc produces multiple waveforms in parallel — sine, sawtooth, square, triangle — at the pitch set by voct. This patch blends two:

osc.sawtooth -[0.6]-> mix.in[saw]
osc.square   -[0.5]-> mix.in[sq]

The scale factors are the blend ratio: 60% sawtooth, 50% square. The total (1.1) is a little hot deliberately — the limiter at the end of the chain catches the peaks while keeping the bright bite of both shapes.

PolySum([saw, sq]) is a two-channel summing mixer with named inputs. The names saw and sq are arbitrary — readable labels for the connections. Numeric indices (PolySum(2), mix.in[0]) work just as well.

drift: 0.04 on PolyOsc adds a small random per-voice detune that makes massed voices sound fuller. Set it to 0.0 for a perfectly in-tune (sterile-sounding) stack; raise it for thicker detuning.

Amplitude shaping

Without a VCA, every voice would sound continuously. The amplitude envelope shapes the dynamics of each note:

kbd.trigger -> amp_env.trigger
kbd.gate    -> amp_env.gate
mix.out     -> vca.in
amp_env.out -> vca.cv

PolyAdsr produces a per-voice control signal that:

1. Rises to 1.0 over attack seconds when triggered.
2. Falls to sustain (0.7) over decay seconds.
3. Holds at sustain while the gate is high.
4. Falls to 0.0 over release seconds on gate-off.

PolyVca multiplies the audio by the envelope. Output is 0 when the envelope is 0 (silent voice), audio when the envelope is 1 (full-amplitude voice).

The values here — fast 0.003 (3 ms) attack, moderate 0.18 decay, high 0.7 sustain, short 0.18 release — give a punchy, plucked feel that still holds notes for sustained chords. Automate the host controls on these parameters from a DAW track to morph the envelope shape over a phrase.

Filter and filter envelope

The filter sits after the VCA, which is the unusual choice here — classic synth topologies often put it before. Putting it after means the filter sees the amplitude-shaped voice, so filter envelope modulation interacts with the amp envelope rather than being independent.

vca.out         -> filt.in
filt_env.out -[1.0]-> filt.voct

filt.voct is a V/oct cutoff input — the filter cutoff is set in V/oct just like an oscillator’s pitch. The filter envelope adds to the base cutoff (1.2kHz) in V/oct units, opening the filter on note attack and closing it during release.

-[1.0]-> filt.voct is full-depth modulation. The filter envelope’s own shape (slow attack, moderate decay, low sustain) gives the characteristic “pluck” — bright on the onset, then darker. Lower the scale (-[0.5]->) for a subtler sweep; raise it (-[2.0]->) for an aggressive, almost over-the-top opening.

resonance: 0.55 adds emphasis at the cutoff frequency — nasal and slightly vocal. saturate: true enables soft-clipping inside the filter, adding warmth when driven hard. Both are good targets for host automation.

Effects bus

The filter feeds a stereo delay and a stereo limiter:

filt.out -[0.1]-> delay.in
delay.out       -> lim.in
lim.out         -> out.in

The -[0.1]-> scaling into the delay drops the level by ~20 dB because the limiter at the end of the chain is set to -3dB threshold — too hot a signal hits the limiter constantly and loses its dynamics. With this scaling the delay sits at a comfortable level under the dry voice.

StereoDelay operates on a stereo bus: its in and out are stereo ports. The mono → stereo broadcast at filt.out -> delay.in is implicit; the delay itself can produce stereo movement via pingpong: true, which alternates taps between left and right.

The StereoLimiter catches the cumulative peaks of 16 voices and prevents clipping at the AudioOut.

What to automate from a DAW

The natural automation targets for this voice, in the order you’d typically reach for them:

To make these available as host parameters, declare them as host controls in the patch (see DSL reference, Host controls). They then show up in the DAW’s parameter list for automation, modulation, and per-track recall.

Variations

The other patches under examples/synths/:

• pad.patches — slow attack, two detuned oscillator layers, long hall reverb. Same skeleton; pad-shaped envelopes.
• bass.patches — monophonic-feeling poly with a low-pass set for sub frequencies, tight envelopes.
• pluck.patches — almost no sustain, fast filter envelope, short delay.
• bell.patches, fm_pad.patches — FM-style spectra, longer envelopes.

Reading two or three of these side-by-side is the fastest way to see which parameters carry the character of a sound and which are incidental.

Hot-reload while authoring

When you save the file, the engine swaps in the new graph without stopping audio. Modules whose name and type are unchanged carry their state — osc’s phase, delay’s buffer, amp_env’s position all survive. This is the edit-reload cycle: treat it as a REPL for iteratively shaping a sound rather than as a performance feature.

Anatomy of a self-contained patch

This chapter walks through examples/tracker_three_voices.patches, a piece for three voices — bass, two leads — driven entirely by the tracker sequencer. No external MIDI; the patch is the composition.

If Anatomy of a synth voice shows how a voice produces sound, this chapter shows how the sequencer drives it.

The patch is over 100 lines and full of detail; we’ll read it in chunks. The full file is at examples/tracker_three_voices.patches.

Three things at once

A self-contained piece typically has three layers:

1. The composition. song and pattern blocks declaring what notes play when. Top of the file, before the patch block.
2. The voice machinery. template blocks that wrap synth-voice wiring so the patch can stamp out one per voice. Also top-of-file.
3. The patch. A MasterSequencer, one PatternPlayer per voice, instances of the voice templates, mixer, effects, output.

Reading order matters: skim top to bottom for the lay of the land (songs → templates → patch), then re-read each layer in detail.

The song

song demo(bass, lead1, lead2) {
    pattern bass_verse {
        note: C2  .  .  ~  Eb2 .  G1  .  C2  .  .  ~  Ab1 .  .  .
        vel:  1.0 .  .  ~  0.8 .  0.9 .  1.0 .  .  ~  0.7 .  .  .
    }

    pattern bass_chorus { ... }
    pattern lead1_verse { ... }
    pattern lead1_chorus { ... }
    pattern lead2_verse { ... }
    pattern lead2_chorus { ... }
    pattern lead2_fill  { ... }

    play {
        (bass_verse,  lead1_verse,  lead2_verse
        bass_verse,  lead1_verse,  lead2_verse) * 2
        (bass_chorus, lead1_chorus, lead2_chorus
        bass_chorus, lead2_chorus,   lead2_fill) * 2
    }
}

A song declares its voices (demo(bass, lead1, lead2)). The patterns inside reference those voice names. The play { ... } block lists which patterns are active simultaneously for each row of the song, with (...) * N for repetition.

Pattern syntax in one breath

• note: and vel: are channel rows. The names are conventions; any identifier works. Each step on a row is one slot.
• C2, Eb2, G1, Ab1 — note names with octave.
• . — rest. Silence on this step; the previous gate ends.
• ~ — tie. Hold the previous note’s gate across this step without re-triggering.
• 1.0, 0.8 — bare floats. Used on vel: for velocity.

Step counts must match across rows in a pattern. Here every row has 16 steps; the sequencer treats them as 16 sixteenth-notes (with rows_per_beat: 4, four steps per beat = sixteenth notes).

Slides (C4>Eb4), continues (x), and repeats (*N) extend the basic syntax — see the DSL reference under Patterns and Songs for the full set.

The play block

play {
    (bass_verse,  lead1_verse,  lead2_verse
    bass_verse,  lead1_verse,  lead2_verse) * 2
    (bass_chorus, ...) * 2
}

A row names which pattern plays on each voice for the next chunk of song time. Commas separate columns within a row; newlines separate rows. Parenthesised groups can be repeated with * N.

Reading the first group: row 1 plays bass_verse on bass, lead1_verse on lead1, lead2_verse on lead2; row 2 plays the same three again; the group repeats twice — so four iterations of “verse” before the chorus block starts.

The voice template

template voice(attack: float = 0.01, decay: float = 0.1,
               sustain: float = 0.7, release: float = 0.001,
               cutoff: float = 6.0, q: float = 0.0,
               glide_ms: float = 0.0) {
    in:  voct, gate, trigger, velocity
    out: audio

    module osc    : Osc
    module env    : Adsr { attack: <attack>, decay: <decay>,
                           sustain: <sustain>, release: <release> }
    module vca    : Vca
    module filt   : Svf { cutoff: <cutoff>, q: <q> }
    module vel_vca: Vca
    module glide  : Glide { glide_ms: <glide_ms> }

    $.voct      -> glide.in
    glide.out   -> osc.voct
    $.gate      -> env.gate
    $.trigger   -> env.trigger

    osc.sawtooth -> filt.in
    filt.lowpass -> vca.in
    env.out      -> vca.cv
    vca.out      -> vel_vca.in
    $.velocity   -> vel_vca.cv
    vel_vca.out  -> $.audio
}

A monophonic voice (not poly — see below) with the standard oscillator → filter → VCA → velocity-VCA chain. Differences from the previous chapter’s lead voice:

• Monophonic. No Poly* prefix anywhere. The tracker plays one note per voice per step; there is no polyphony required.
• Glide. Glide smooths the pitch CV — when a step plays a different note from the previous step, the pitch slews to it instead of jumping. glide_ms: 0.0 disables it.
• Velocity VCA. The pattern’s vel: row drives a second VCA after the amp envelope, so velocity scales the dynamic shape.
• Svf filter. State-variable filter with cutoff in V/oct units. Cheaper than the lead voice’s PolyLowpass.

The template’s interface is voct, gate, trigger, velocity in and audio out — the same shape PolyMidiToCv would feed, but mono.

A second template (sq_voice) is a square-wave variant for lead2 — same skeleton, swapped oscillator output and different defaults.

The patch

The actual graph. Read it top-down:

Sequencer + pattern players

module seq: MasterSequencer([bass, lead1, lead2]) {
    song: demo,
    bpm: 120,
    rows_per_beat: 4,
    loop: true,
    autostart: true,
    swing: 0.75
}

module bass_pp:  PatternPlayer([note, vel])
module lead1_pp: PatternPlayer([note, vel])
module lead2_pp: PatternPlayer([note, vel])

seq.clock[bass]  -> bass_pp.clock
seq.clock[lead1] -> lead1_pp.clock
seq.clock[lead2] -> lead2_pp.clock

MasterSequencer consumes the song (song: demo), runs at bpm: 120 with 4 rows per beat (sixteenth notes), loops the play block, autostarts on load, and applies 0.75 swing.

For each voice it emits a clock[<voice>] output: a stream of “row events” that name which pattern is active, which step is current, and the step’s data.

PatternPlayer([note, vel]) listens to a clock and unpacks the two named channels — note and vel. It exposes per-channel outputs:

• pp.cv1[note] — the pitch CV from the note: row.
• pp.gate[note] — gate held high during notes (low during .).
• pp.trigger[note] — single-sample pulse at step start.
• pp.cv1[vel] — the velocity CV from the vel: row.

The names cv1, gate, trigger are the PatternPlayer’s fixed port set; the [name] index is the channel from the pattern.

Voices

module bass_v: voice(
    attack: 0.005, decay: 0.15, sustain: 0.6, release: 0.1,
    cutoff: 3.5, q: 0.3, glide_ms: 40.0
)

bass_pp.cv1[note]     -> bass_v.voct
bass_pp.gate[note]    -> bass_v.gate
bass_pp.trigger[note] -> bass_v.trigger
bass_pp.cv1[vel]      -> bass_v.velocity

Bass uses the voice template with 40ms glide for portamento between notes, a tight envelope, and a moderately low filter cutoff. lead1_v and lead2_v instantiate the same shape with different parameters; lead2_v uses sq_voice for a different oscillator waveform.

Mixer with sends

module mix: StereoMixer([bass, lead1, lead2]) {
    @bass:  { level: 0.7, pan:  0.0 },
    @lead1: { level: 0.5, pan: -0.4, send_a: 0.3 },
    @lead2: { level: 0.5, pan:  0.4, send_a: 0.3 }
}

bass_v.audio  -> mix.in[bass], ~meter+osc+spectrum(bass)
lead1_v.audio -> mix.in[lead1]
lead2_v.audio -> mix.in[lead2]

Three-channel stereo mixer. Bass is centred and loudest; the two leads are softer, panned left and right, with a 30% send to bus A.

The ~meter+osc+spectrum(bass) at the end of bass_v.audio -> attaches a tap to the cable, exposing live meter / scope / spectrum data to the GUI. See Visualising patches for taps.

Effects bus

module delay: StereoDelay(2) {
    delay_ms: 750, feedback: 0.4, dry_wet: 1.0
}
mix.send_a  -> delay.in
delay.out   -> mix.return_a

module reverb: FdnReverb {
    size: 0.45, brightness: 0.6, mix: 0.2, character: plate
}
module lim: StereoLimiter { threshold: 0.85 }

mix.out    -> reverb.in
reverb.out -> lim.in

module out: AudioOut
lim.out -> out.in

Two effects layers:

1. Send-return. mix.send_a carries the delay-bound signal from the leads (no bass). The delay’s wet-only output (dry_wet: 1.0) returns to mix.return_a, which the mixer sums into its main output. Standard send-return topology.
2. Master bus. mix.out (everything: voices + return) → reverb → limiter → AudioOut. The reverb is plate-flavoured with moderate mix.

Design notes

A few decisions worth explaining:

Monophonic voices over poly. The sequencer plays one note per voice per step. There’s no polyphony to allocate, so each voice is a mono chain — cheaper, simpler, and the template’s parameter list controls per-voice character without any shared poly cost.

Svf over Lowpass. State-variable filter is cheaper than a biquad cascade and the leads don’t need the steeper rolloff. Bass might benefit from a steeper filter; an exercise for the reader.

Pattern length 16. With rows_per_beat: 4 that’s exactly four beats per pattern. Different pattern lengths within a song are fine (some voices can sustain across multiple steps via ~), but keeping them aligned to common multiples simplifies the timing.

Swing on the sequencer, not per-voice. swing: 0.75 shifts off-beats slightly later for groove. Applying it at the sequencer means every voice swings in sync.

Autostart in the player; transport-driven in a DAW. With autostart: true, the piece plays as soon as the patch loads in patch_player. If you load it as a CLAP plugin in a DAW, you may prefer autostart: false and wire seq.start to the host’s transport — but that’s a host-integration decision, not part of the patch itself.

Mixing the modes

There’s no rule preventing a sequenced backing layer from coexisting with an externally-driven lead. A MasterSequencer driving a few voices and a PolyMidiToCv driving a lead voice can live in the same patch — the engine doesn’t care where the gate edges come from.

Self-contained vs. externally-driven is a property of the wiring, not a setting on the player.

The edit-reload cycle

When you save a .patches file, the engine builds the new graph and swaps it in without stopping the audio. Module instances whose name and type are unchanged carry their state across the swap; the rest are freshly instantiated.

This makes Patches’ development loop closer to a REPL than to a compile-run-listen workflow. Save → hear the difference → save again. The audio never stops; small edits sound like parameter tweaks. That’s the edit-reload cycle.

This is a development feature, not a performance one. (Live coding on top of it is possible — the cycle is robust enough — but the design centres on iteration speed during patch authoring, not on on-stage editing.)

The reload cycle

1. You edit the .patches file and save.
2. The watcher detects the change and feeds the new source to the DSL parser.
3. The parser produces a FlatPatch — a flat list of module declarations and connections after template expansion.
4. The interpreter validates the FlatPatch against the module registry: module types exist, port names are real, parameter types are correct, cable kinds match.
5. If validation fails, diagnostics are surfaced (TUI log, plugin log pane) and the running patch continues unchanged.
6. If validation succeeds, the planner builds a new ExecutionPlan.
7. The plan is sent to the audio thread via a lock-free ring buffer. The audio thread picks it up at the start of its next processing block and swaps it in.

The audio stream never stops. There is no gap, no fade. The new plan takes effect between two consecutive samples.

What survives a reload

The planner matches modules in the new patch against those in the running patch by name and type. A module named osc of type PolyOsc in the old patch matches a module named osc of type PolyOsc in the new patch — its instance is carried forward, its internal state untouched.

State that survives includes:

• Oscillator phase. A 440 Hz oscillator running for ten seconds continues from its current phase, not from zero.
• Filter state. The filter’s internal delay buffers (which determine its current resonant behaviour) are preserved.
• Envelope position. An envelope in its sustain phase stays in sustain.
• Delay buffers. A delay line full of audio retains its contents.
• VCA and mixer state. Per-channel summation accumulators.

The practical effect is that parameter edits sound smooth. Changing a filter cutoff mid-note produces a continuous sweep, not an abrupt reset.

What resets

A module is not matched, and is freshly instantiated, when:

• It is new in the patch (didn’t exist before).
• Its type changed. Replacing Osc with PolyOsc keeps the name but the type is different, so the old instance can’t be reused.
• Its name changed. Renaming osc to oscillator looks like a different module to the planner.

Freshly instantiated modules start from initial state: oscillator phase at zero, envelopes idle, delay buffers empty.

Modules that existed before and are absent from the new patch are removed. Their memory is reclaimed on a background thread — the audio thread doesn’t deallocate.

Parameter updates

When a surviving module’s parameters change (cutoff: 600Hz → cutoff: 800Hz), the new values are applied to the existing instance. The module isn’t reinstantiated — only its parameter fields are updated.

Most modules respond on the next sample. Some (filters with biquad coefficients, oversampling stages) recompute periodically, so a change may take effect over a few samples rather than instantaneously. This usually sounds more natural than a hard parameter snap.

Connectivity changes

When you add, remove, or reroute cables, the planner rewires the buffer pool and notifies affected modules of their new port assignments. Modules that care about connectivity (an oscillator that skips computing an output waveform if nothing’s connected) can adapt.

The buffer pool itself is stable across reloads — unchanged cables keep their buffer slots, so signals on un-touched cables continue without interruption. Only the rewired cables see a fresh buffer.

Error recovery

If the new file has a syntax error or fails validation, the running patch is unaffected. Diagnostics name the file position (line, column) and the rule that failed. Fix and save again — the next successful parse triggers a reload.

This means you can save speculatively without fear. A half-finished connection, a misspelled module type, an unclosed brace — none of these crash the running audio. They just fail to reload until you fix them.

Thinking about identity

The matching rule — same name, same type — is the mental model.

• Want a module to survive a reload? Keep its name and type the same.
• Want it to reset? Change one of them.

A common pattern: rename a module temporarily to force a reset (a delay line full of stale audio, for example, can be cleared by renaming it, saving, then renaming back). Less brutally, change its type to a no-op variant and back.

Structural changes — adding new modules, removing old ones, rewiring — happen smoothly. The only thing the planner cannot carry across is a change in a module’s fundamental identity.

Working flow

A productive iteration loop:

1. Start patch_player your.patches (or load the patch as a CLAP plugin).
2. Make a small edit — change one parameter, one connection, add one module.
3. Save.
4. Listen.
5. Repeat.

If you’re tempted to make a big edit (“rewrite the filter section entirely”), save halfway. The patch keeps running with the partial edit — you’ll either hear the half-rewrite sound interesting, or the reload will fail with a diagnostic that tells you exactly what to fix.

The cost of saving is small enough that “save to check” is a valid debugging step. Use it.

In the plugin

Inside a DAW, the CLAP plugin watches the file the same way the player does. Edit the patch file in any editor, save, and the plugin reloads in place. State survival rules are identical.

If you edit through the plugin’s webview (no in-place editor yet — this is via your external editor, watched), the cycle is the same. The plugin’s Reload button forces a recompile from the current file contents (useful when the file watcher missed an event, or to retry after fixing a previously-failing edit).

What about live performance?

The cycle is robust enough to perform with — the audio doesn’t drop and structural edits stay smooth. People do live-code with Patches.

But the cycle is designed around iteration speed during authoring, not around the constraints of a stage: there’s no syntax-aware editor mode, no commit/discard distinction, no “stage this change for the next downbeat” mechanism. If those things matter for your performance, you’ll either work around them or ask for them as features.

Authoring is the headline use; performing is a happy accident of the cycle being fast and crash-safe.

Visualising patches

The text DSL is the source of truth, but for an unfamiliar patch a diagram is faster to read than the file. Patches can render any .patches file as an SVG signal-flow graph: modules as boxes, ports on the sides, cables as routed arrows between them.

Rendering is a feature of the language server (patches-lsp), exposed through:

• The VS Code extension command Show Patch Graph.
• The LSP patches/renderSvg custom request, for any LSP client.
• The patches_svg library crate, for programmatic use.
• The patches-svg binary, shipped by the patches-svg workspace crate (publish = false, build with cargo build -p patches-svg --bin patches-svg).

From VS Code

Install the VS Code extension. Open a .patches file. Then either:

• Right-click in the editor → Show Patch Graph.
• Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → Patches: Show Patch Graph.

A side panel opens with the SVG, scrollable and zoomable. The panel re-renders when you save the file (the LSP refreshes on each successful parse), so editing the patch and watching the graph update side-by-side is a usable authoring loop.

If the patch has a parse error, the panel shows the diagnostic instead of the (stale) graph. Fix the error and save; the graph returns.

Reading the diagram

A rendered patch is a sequence of columns laid out left-to-right by topological depth: sources (oscillators, MIDI sources, sequencers) on the left, sinks (AudioOut) on the right, everything else ordered by the longest signal path that reaches it.

Inside each module box:

• The module type is the label across the top (PolyOsc, Adsr, StereoMixer).
• The instance name is below the type, smaller (osc, env, mix).
• Input ports are dots on the left edge, labelled with their port names.
• Output ports are dots on the right edge, likewise labelled.

Cables are arrows from output dots to input dots. Scaled cables (-[0.5]->) carry the scale as a small label near the destination.

Mono cables are drawn as single lines; poly cables and stereo cables are styled slightly thicker, with a small annotation marking the kind. (Exact visual coding may evolve — when in doubt, the SVG’s CSS classes name each kind.)

The layout is computed by the rust-sugiyama crate (a Sugiyama- family layered-graph layout). Crossings are minimised but not eliminated; expect occasional overlaps in dense patches.

Themes

Two built-in themes:

• Dark (default) — light strokes and labels on a dark background. Suited to the VS Code dark theme.
• Light — dark strokes on a light background. Suited to the VS Code light theme and to embedding in print.

The VS Code extension currently renders with the default (dark) theme. To render a light SVG programmatically:

#![allow(unused)]
fn main() {
use patches_svg::{render_svg, SvgOptions, Theme};

let svg = render_svg(
    &flat_patch,
    &flat_patch.module_descriptors,
    &SvgOptions { theme: Theme::Light, ..Default::default() },
);
}

SvgOptions has a handful of additional knobs (margins, font size, port-label visibility); see the crate’s source for the current set.

Programmatic rendering

If you want diagrams in a build pipeline (auto-generated docs, README badges, a static-site catalogue), depend on patches_svg directly:

[dependencies]
patches-dsl = { path = "../patches-dsl" }
patches-svg = { path = "../patches-svg" }

The flow is: parse the source with patches_dsl, flatten it (template expansion, stereo desugaring), then call patches_svg::render_svg with the resulting FlatPatch and the module-descriptor table. The output is a String of SVG markup ready to write to disk or embed.

Two consumers in-tree:

• patches-lsp calls render_svg from its patches/renderSvg endpoint.
• patches-vscode requests SVGs from the LSP and renders them in a webview panel.

When the diagram helps

Reading SVGs is the fastest way to:

• Onboard onto an unfamiliar patch. Layout shows the architecture at a glance: subtractive, FM, sequencer-driven, etc.
• Spot fan-out you forgot about. A module driving five destinations is obvious in the diagram; in text it’s spread across a dozen lines.
• See the feedback structure. Cycles in the graph are drawn as back-edges and are unmissable.

It’s less useful while authoring, when the text is faster to edit than the diagram is to scan. Authors typically read the text and use the diagram as a sanity check after structural changes.

Module reference

Each module type is documented with its ports, parameters, and behaviour. The canonical source of truth for port names and parameter ranges is the doc comment on each module struct in patches-modules/src/.

Oscillators

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

Osc — Mono oscillator

A single-voice oscillator with multiple waveform outputs.

Parameters

Inputs

Outputs

PolyOsc — Polyphonic oscillator

Per-voice oscillator. Each voice runs independently at the pitch set by the voct poly cable.

Parameters

Inputs

Outputs

Supersaw — HyperSaw and PolyHyperSaw

A supersaw (JP-8000 style) is a stack of detuned sawtooth copies summed to one voice. HyperSaw/PolyHyperSaw use 9 copies — one centre saw plus four pairs of side saws, detuned symmetrically below and above the centre pitch. The copies run at slightly different frequencies, so they slowly drift in and out of phase with one another; that continuous beating is the wide, animated character you cannot get from a single saw or a static wavetable.

Three controls shape the ensemble:

• spread — the detune width. 0 collapses every copy onto the centre pitch (a plain unison saw, no beating); 1 pushes the outermost pair to ±50 cents. The pairs are spaced nonlinearly (inner pairs detuned much less than the outer ones).
• density — how many of the four side pairs are active, faded in inner→outer. The fade is loudness-normalised, so turning density up thickens the sound without a level jump.
• mix — the centre↔side balance. 0 is the clean centre saw alone; 1 is the full stack with the centre and sides together. The summed output is normalised to stay within [-1, 1].

FM here is vibrato, not timbre. Unlike Osc/PolyOsc, which recompute pitch every sample, the supersaw recomputes all 144 increments (9 copies × 16 voices) only at the control-rate interval — recomputing them per sample is not affordable. Pitch and FM are therefore sampled at control rate: fm is a vibrato input, and there is no hard-sync and no phase modulation (syncing would re-align the copies and kill the beating that is the whole point). See ADR 0078 for the design and the fixed-point, autovectorised kernel behind it.

The copies’ start phases are randomised once at construction, so there is no thin attack and no comb-filtered coincident-wrap aliasing.

A worked patch using PolyHyperSaw into a filter and amp lives in examples/synths/hypersaw_lead.patches.

HyperSaw — Mono supersaw

A single detuned-saw ensemble. Runs the 16-voice kernel and reads one voice; mono is not the performance case.

Parameters

Inputs

Outputs

PolyHyperSaw — Polyphonic supersaw

The 16-voice counterpart: one detuned ensemble per voice, driven by per-voice voct/fm. spread/density/mix CV are mono (shared across voices) so the detune ratios are computed once per control interval and reused for every voice; per-voice spread is deferred.

Parameters

Same as HyperSaw (frequency, fm_type, spread, density, mix).

Inputs

Outputs

Lfo — Low-frequency oscillator

Multi-waveform LFO intended for modulation signals. Runs at audio rate.

rate is a frequency in Hz (range 0.01–20.0 Hz, default 1.0 Hz). This is not a V/oct value — it is a plain frequency. rate_cv adds linearly to rate in Hz (effective rate is clamped to 0.001–40.0 Hz).

Parameters

Inputs

Outputs

Envelopes

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

Adsr — Multi-channel DADSR envelope with built-in VCA

Multi-channel Attack-Decay-Sustain-Release envelope generator with an optional pre-attack Delay phase and built-in VCA pass-through. One module emits N independent envelopes (one per channel) driven by a single shared trigger and gate.

With channels = 1 (the default) it behaves as a conventional single-channel ADSR — env.out, env.vca_in, env.vca_out address channel 0 implicitly. Use Adsr([amp, filt, vib]) or Adsr(3) to get multiple envelopes per trigger/gate.

Each channel has its own delay/attack/decay/sustain/release/shape, and an optional VCA stage: if vca_in[c] is connected, vca_out[c] emits vca_in[c] * env[c]. Useful for tying amplitude, filter, and modulation envelopes to the same note event without wiring N separate modules. A rising trigger enters the per-channel Delay phase (output held at 0 for delay[c] seconds) before Attack begins. Releasing the gate during Delay returns the channel to Idle without emitting any envelope.

Inputs

Outputs

Parameters

Env — Multi-stage breakpoint envelope with key-follow

Where Adsr has a fixed attack/decay/sustain/release shape, Env runs an arbitrary number of (time, level, curve) stages with a designated sustain stage — enough to express D50-style contours ADSR cannot (attack spike → dip → secondary swell → sustain). The stage count is the module’s channels axis: Env(5) is a five-stage envelope. One module is one envelope (mono); use multiple instances for multiple envelopes.

Stages 0..sustain_stage form the pre-sustain contour; the envelope holds at level[sustain_stage] while the gate is high, then runs the remaining stages sustain_stage+1..N as the release tail on gate-off. Designate a final stage with level = 0 for a release to silence. A re-trigger restarts from the current level (no click), and a gate-off during the pre-sustain contour jumps straight into the release tail.

Key-follow shortens stage times with pitch, as real resonators decay faster up the keyboard: time_scale = 2^(-keyfollow * (voct - ref_key)), so keyfollow = 1.0 halves all stage times one octave above ref_key. It is applied per tick, so a bending voct re-scales the contour live.

Velocity scales stage levels: the effective velocity (1.0 if the input is unconnected) is mapped to a level multiplier 1 - vel_depth * (1 - velocity) and latched at the trigger, so an in-flight envelope keeps a stable scaling.

Route out to an oscillator voct / phase_mod or a filter cutoff for the D50 attack pitch-blip or filter sweep — that’s a patch idiom, not a port.

Inputs

Outputs

Parameters

PolyAdsr — Per-voice DADSR

Same envelope shape as Adsr (delay/attack/decay/sustain/release/shape) but each voice has independent state, driven by per-voice trigger / gate poly cables. Optional per-voice VCA via vca_in.

Inputs

Outputs

Parameters — same names and ranges as Adsr. Parameters apply identically to all voices.

PolyEnv — Per-voice multi-stage envelope

The 16-voice form of Env: same multi-stage contour, key-follow, and velocity scaling, but each voice holds independent state driven by per-voice trigger / gate / voct / velocity poly cables. All voices share one stage configuration. The stage count is the channels axis (PolyEnv(5) = five stages); sustain_stage and the release-tail semantics are identical to Env.

Key-follow and velocity are computed per voice: time_scale = 2^(-keyfollow * (voct[v] - ref_key)) and the level multiplier 1 - vel_depth * (1 - velocity[v]), latched at each voice’s trigger. Unconnected voct reads as 0 and unconnected velocity as 1.0.

Inputs

Outputs

Parameters — same names, ranges, and defaults as Env (time[i], level[i], curve[i], sustain_stage, keyfollow, ref_key, vel_depth). Parameters apply identically to all voices.

Filters

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

All filter modules implement a resonant biquad (Transposed Direct Form II).

Note: The legacy Filter module name is no longer supported. Use Lowpass instead.

Lowpass / Highpass

Mono resonant filters.

Parameters

Inputs

Outputs

Bandpass

Mono resonant bandpass filter.

Parameters

Inputs

Outputs

PolyLowpass / PolyHighpass

Per-voice versions of Lowpass / Highpass. Each voice maintains independent biquad state. Same parameters as their mono counterparts. CV inputs carry poly cables; modulation is applied per-voice.

Inputs

Outputs

Svf

Mono State Variable Filter (Chamberlin topology). Produces lowpass, highpass, and bandpass outputs simultaneously from a single audio input. All three outputs can be used at once — they share the same two integrator state variables and cost no extra computation per connected output.

Unlike the biquad filters above, Svf is capable of self-oscillation: at high q values the filter will sustain a sine wave at the cutoff frequency without any audio input. Noise or other signals act as an exciter to kick the filter into ringing.

Parameters

Inputs

Outputs

Warning: At q values above ≈ 0.95 the filter self-oscillates. Loud audio input at those settings can drive the output to clip. Scale the output down or use a VCA after the filter if this is a concern.

PolySvf

Per-voice version of Svf. Each voice maintains independent integrator state. All parameters and CV semantics are identical to Svf; all ports carry poly cables.

Parameters

Same as Svf: cutoff and q.

Inputs

Outputs

PolyBandpass

Per-voice version of Bandpass. Same parameters as Bandpass.

Inputs

Outputs

Amplifiers & VCAs

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

Vca — Mono voltage-controlled amplifier

Multiplies an audio signal by a control signal.

Inputs

Outputs

PolyVca — Per-voice VCA

Same as Vca but operates on poly cables, multiplying each voice independently.

Inputs

Outputs

Mixers

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

Sum — Unweighted mono sum

Sums N mono inputs into one mono output with no level control.

module mix : Sum(channels: 4)

Inputs

Outputs

Mixer — Mono mixer with sends and mute/solo

N-channel mono mixer. Each channel has level CV, two auxiliary send buses, and mute/solo. If any channel is soloed, only soloed (non-muted) channels contribute to the output.

module mix : Mixer(channels: 4)

Parameters (all indexed per channel)

Inputs

Outputs

StereoMixer — Stereo mixer with pan, sends and mute/solo

N-channel stereo mixer. Each channel has level, pan, two send buses, and mute/solo.

module mix : StereoMixer(channels: 4)

Parameters (all indexed per channel)

Inputs

Outputs

PolySum — Unweighted poly sum

Sums N poly inputs voice-by-voice with no level control.

module mix : PolySum(channels: 2)

Inputs

Outputs

PolyMixer — Poly mixer with level and mute/solo

N-channel poly mixer with per-channel level, mute, and solo. Level CV inputs are mono (applied uniformly across all voices of that channel).

module mix : PolyMixer(channels: 2)

Parameters (indexed per channel)

Inputs

Outputs

StereoPolyMixer — Stereo poly mixer with pan and mute/solo

N-channel stereo poly mixer. Outputs two poly cables (left and right). Level and pan CV inputs are mono.

module mix : StereoPolyMixer(channels: 2)

Parameters (indexed per channel)

Inputs

Outputs

PolyToMono — Collapse poly to mono

Sums all active voices of a poly cable into a single mono signal.

Inputs

Outputs

MonoToPoly — Broadcast mono to all voices

Copies a mono signal into every voice slot of a poly cable.

Inputs

Outputs

StereoSum — Unweighted stereo sum

Sums N stereo inputs into one stereo output, no level control. Useful for collapsing voice or bus outputs into a single stereo path.

module mix : StereoSum(channels: 3)

Inputs

Outputs

Noise generators

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

Noise — Mono noise generator

Four coloured noise outputs from a single module. Only connected outputs are computed, so unused colours have no CPU cost.

The four outputs span a range of spectral slopes. White noise is the source for all other colours: pink is derived by filtering white, brown by integrating white, and red by integrating brown.

Outputs

All outputs are in the range [−1, 1]. Each instance has its own PRNG state seeded from the module’s instance ID, so two Noise modules in the same patch produce independent signals.

Example — white noise as a sound source

Noise noise
AudioOut out

noise.white -> out.in

Example — pink noise for modulation

Noise lfo_noise
Vca filter_env { frequency: 440Hz }

lfo_noise.pink -> filter_env.cv

PolyNoise — Polyphonic noise generator

Identical to Noise but with poly outputs. Each voice has its own independent PRNG and filter state, so voices are uncorrelated with each other and with any Noise instance.

Outputs

PolyNoise is useful for adding independent per-voice variation to polyphonic patches — for example, routing the white output through a PolyVca to add noise to each voice’s amplitude independently.

Example — per-voice breath noise

patch {
    module src       : PolyNoise
    module noise_vca : PolyVca
    module env       : PolyAdsr { attack: 0.005, decay: 0.1, sustain: 0.2, release: 0.2 }
    module midi      : PolyMidiToCv

    midi.gate -> env.gate
    env.out   -> noise_vca.cv
    src.white -> noise_vca.in
}

Sequencers & clocks

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

Clock — Tempo-locked trigger generator

Generates bar, beat, quaver, and semiquaver trigger pulses from a configurable BPM and time signature. All outputs are derived from a single beat-phase accumulator, so they are always phase-locked to each other.

Each output fires a one-sample pulse (1.0) at the relevant boundary and is 0.0 on all other samples.

Parameters

Outputs

HostTransport — DAW transport readback

Exposes the host DAW’s transport state as CV signals. In standalone mode the player synthesises a static transport (tempo from --bpm, no playhead motion).

Outputs

TempoSync — BPM + subdivision → milliseconds

Converts a tempo (in BPM) and a fixed musical subdivision into a duration in milliseconds. Drives delay_ms-style inputs on Delay, MsTicker, etc. for tempo-locked timing.

Parameters

Inputs

Outputs

MsTicker — Millisecond-paced trigger

Fires a trigger every ms milliseconds with a corresponding gate.

Inputs

Outputs

TriggerToSync / SyncToTrigger

A pair of converters between the two trigger encodings: legacy mono level pulses (≥ 0.5 high) and the sub-sample sync cable. Use when bridging modules that expect different encodings.

TriggerToSync — mono in → trigger out. SyncToTrigger — trigger in → mono out (rising-edge pulse).

Tracker sequencer

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

The tracker sequencer is a two-module system for song-driven step sequencing. A MasterSequencer reads a named song from the patch’s tracker data and drives one or more PatternPlayer modules via poly clock buses. Pattern and song data are defined in the .patches file using pattern and song blocks (see DSL reference — Patterns & songs).

How it fits together

┌─────────────────────┐
│  MasterSequencer    │
│  song: my_song      │──clock[bass]──▶ PatternPlayer (channels: [note, vel])
│  bpm: 120           │──clock[lead]──▶ PatternPlayer (channels: [note, vel])
│  rows_per_beat: 4   │──clock[drums]─▶ PatternPlayer (channels: [hit])
└─────────────────────┘

The MasterSequencer walks through the song order, emitting timing and pattern-selection data on each clock bus. Each PatternPlayer decodes that data, looks up the relevant pattern, and outputs cv/trigger/gate signals per channel.

MasterSequencer — Song-driven transport

Drives song playback with transport controls, swing, and a poly clock bus per song channel.

Inputs

Outputs

The clock bus carries four poly voices:

Parameters

Shape arguments

The channels shape argument defines the song channels. Use named aliases to match the song’s lane names:

module seq: MasterSequencer(channels: [bass, lead, drums]) {
    song: my_song, bpm: 140, rows_per_beat: 4
}

PatternPlayer — Pattern step sequencer

A generic multi-channel step sequencer that reads a poly clock bus, steps through pattern data, and outputs cv1/cv2/trigger/gate signals per channel. The PatternPlayer does not know whether its channels are notes, drums, or automation — all channels produce the same four output types.

Inputs

Outputs

Shape arguments

The channels shape argument defines the pattern channels. Use named aliases to match the pattern’s channel names:

module pp: PatternPlayer(channels: [note, vel])

Output conventions

For note channels, cv1 carries the V/oct pitch (same convention as Osc) and trigger/gate signal note-on events. For drum/trigger channels, trigger fires on each hit and cv2 carries the velocity value.

Step events (ADR 0077 unified grammar)

The PatternPlayer consumes the row-build pass’s resolved StepEffect per cell — a single typed dispatch covering rests, triggered notes, rolls, slides, step-cv changes, and continuation cells. See the DSL reference — Step events for the full cell taxonomy, close rule, and worked-example timelines. The player-side behaviour is:

• Triggered cell (value, value*N, value:cv2, value>value, value>): snap cv1/cv2 at the start of the tick and fire trigger. *N opens a roll; value>value opens-and-closes a one-tick slide; value> opens a multi-tick slide whose close target is resolved when the close cell arrives.
• Step-cv (/value): snap cv1 (and :cv2 if present) at the tick boundary; no trigger. Gate stays high.
• Slide flow (>_, _ absorbed by a slide): no trigger; cv ramps per the slide’s per-channel schedule. Gate stays high.
• Slide close-in-tick (>value): cv1 (and :cv2 if present) ramp to the close value across this tick; no trigger.
• Tie sustain (_ with no open modifier): gate stays high; cv held.
• Tie-spread roll (_ absorbed by a *N anchor): the N sub-triggers spread evenly across the anchor tick plus the absorbed run. Per-tick sub-event placement respects swung tick durations — each sub-event’s sample offset is computed against the current tick’s duration, not the anchor’s, so swing within a span sits precisely on the swung beats.
• Rest (.): gate drops; channel state resets (any open slide is closed at its current cv).

# tie-spread roll across two ticks then a fresh hit
hit: x*3 _ x .

# slide opens at tick 1, ramps through ticks 1+2, lands on G4 at the
# boundary, holds tick 3
note: E4> _ /G4

# slide opens, ramps continuously across three ticks, finishes inside
# tick 3
note: E4> _ >G4

# step cv without retrigger
note: E4 /G4 _

Wiring examples

Drum machine

One PatternPlayer per drum voice, each with a single hit channel:

module kick_pp: PatternPlayer(channels: [hit])
seq.clock[kick] -> kick_pp.clock

module kick_drum: Kick { pitch: 50, decay: 0.4 }
kick_pp.trigger[hit] -> kick_drum.trigger
kick_pp.cv2[hit]     -> kick_vca.velocity

Melodic voice

A PatternPlayer with note and vel channels driving a synth voice:

module bass_pp: PatternPlayer(channels: [note, vel])
seq.clock[bass] -> bass_pp.clock

bass_pp.cv1[note]     -> voice.voct
bass_pp.gate[note]    -> voice.gate
bass_pp.trigger[note] -> voice.trigger
bass_pp.cv1[vel]      -> voice.velocity

Drum synthesis (external bundle)

Source of truth: the doc comments on each module struct in the external patches-drums crate (in the patches-bundles repo) define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

The 808-style electronic drum synthesisers documented on this page are not in the in-tree patches-modules crate. They ship as the patches-drums bundle from the external patches-bundles repository and are loaded at runtime by the host’s plugin scanner. See Implementing a native plugin for how host-loaded bundles work and the host’s stdlib search path (patches_ffi::scanner::stdlib_scanner) for where bundles are discovered.

Each module has a single trigger input (rising edge) and a mono out. They are designed to be driven by the tracker sequencer (see Tracker sequencer) but work with any trigger source.

All drum modules use zero-allocation DSP kernels from patches-dsp and are safe for real-time use.

Kick — 808-style kick drum

A sine oscillator with a fast pitch sweep from a configurable start frequency down to a settable base pitch, shaped by an exponential amplitude decay envelope, with optional tanh saturation for grit and a transient click layer.

Inputs

Outputs

Parameters

Snare — 808-style snare drum

Combines a tuned body oscillator (sine with short pitch sweep) with a bandpass-filtered noise burst. Each path has its own decay envelope; the tone parameter crossfades between them.

Inputs

Outputs

Parameters

ClosedHiHat — Closed hi-hat

Metallic tone from six inharmonic square oscillators mixed with highpass-filtered white noise, shaped by a short decay envelope.

Inputs

Outputs

Parameters

OpenHiHat — Open hi-hat

Same metallic tone engine as closed hi-hat but with a longer decay range. Includes a choke input so a closed hi-hat trigger can cut it short.

Inputs

Outputs

Parameters

Tom — 808-style tom

Shares the kick’s basic architecture (sine oscillator + pitch sweep + amplitude decay) but with a higher pitch range, shorter sweep, and a subtle noise layer for attack texture.

Inputs

Outputs

Parameters

Cymbal — Crash/ride cymbal

Uses the same metallic tone engine as hi-hats but with a higher frequency range, longer decay, and a “shimmer” parameter that adds slow LFO modulation to the partial frequencies.

Inputs

Outputs

Parameters

Clap — 808-style handclap

White noise passed through a bandpass filter, gated by a burst generator to produce the initial “clappy” retriggered transient, then shaped by a longer decay envelope for the tail.

Inputs

Outputs

Parameters

Claves — Claves

A short, bright, resonant click produced by exciting a high-Q bandpass SVF with a single-sample impulse and shaping with a fast decay envelope.

Inputs

Outputs

Parameters

MIDI input

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

MIDI events arrive on the engine-level GLOBAL_MIDI backplane (carrying up to 5 packed events per sample). Modules that need MIDI either read the backplane directly (MidiToCv, PolyMidiToCv, MidiCC) or sit downstream of a MidiIn module which exposes the backplane as a midi cable so other MIDI-processing modules can be chained.

MidiIn — Backplane → MIDI cable

Exposes the engine’s GLOBAL_MIDI backplane as a midi output cable so that MidiSplit, MidiTranspose, MidiArp, MidiDelay, etc. can be chained from it.

Outputs

MidiToCv — Mono MIDI note input

Monophonic: only one note active at a time (last-note priority). Pressing a new key updates pitch immediately; releasing the top key falls back to the previously held key without retriggering. Up to 16 simultaneously held keys are tracked.

V/oct convention

voct is referenced to MIDI note 0 (C0 ≈ 16.35 Hz) at 0 V, with 1/12 V per semitone:

Outputs

Parameters

PolyMidiToCv — Polyphonic MIDI input

Distributes incoming notes across up to 16 voices with LIFO voice stealing. When all voices are occupied the most-recently-allocated voice is stolen.

Outputs

MidiCC — Control-change reader

Reads a configured MIDI CC number from the backplane and emits its normalised value as a mono signal.

Parameters

Outputs

MidiArp — Arpeggiator

Arpeggiates held notes, clocked by an external trigger (e.g. Clock). Refer to the module doc comment in patches-modules/src/midi_arp.rs for the current parameter set and port list.

MidiDelay — MIDI note delay

Delays incoming MIDI events by a configurable number of samples or beats, with optional feedback for repeating echoes. See patches-modules/src/midi_delay.rs for ports and parameters.

MidiSplit — MIDI splitter

Routes incoming MIDI notes to one of several outputs based on channel, velocity, or pitch range. See patches-modules/src/midi_split.rs.

MidiTranspose — MIDI pitch transposer

Transposes note-on / note-off events by a configurable number of semitones. See patches-modules/src/midi_transpose.rs.

MidiDrumset — MIDI note-to-drum mapper

Maps incoming MIDI notes to trigger outputs for drum-voice modules (Kick, Snare, etc). See patches-modules/src/midi_drumset.rs.

Delays & Reverb

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

Delay — Mono multi-tap delay

One shared 4-second delay buffer with N independent read taps. Each tap has its own delay time, gain, feedback, tone, and drive. All tap feedbacks sum back into the buffer write before the next sample. N is set by channels.

module dly : Delay(channels: 2) {
    delay_ms[0]: 250,
    delay_ms[1]: 375,
    feedback[0]: 0.4,
    feedback[1]: 0.3,
    dry_wet:     1.0
}

Parameters (global)

Parameters (per tap i)

Inputs

Outputs

StereoDelay — Stereo multi-tap delay

Two 4-second delay buffers (L and R) sharing a single set of N read taps. Each tap has pan, and an optional pingpong mode that cross-routes feedback (L→R, R→L). N is set by channels.

module dly : StereoDelay(channels: 2) {
    delay_ms[0]: 300,
    delay_ms[1]: 450,
    feedback[0]: 0.35,
    feedback[1]: 0.35,
    pingpong[0]: true,
    pingpong[1]: true,
    pan[0]:      -0.3,
    pan[1]:       0.3
}

Parameters (global)

Parameters (per tap i)

Inputs

Outputs

FdnReverb — Stereo FDN reverb

An 8-line feedback delay network (FDN) with Hadamard mixing matrix, per-line high-shelf absorption, Thiran all-pass interpolation for LFO-modulated reads, and stereo output via orthogonal output gain vectors. Five character archetypes control the room model; size and brightness sweep within each archetype.

module verb : FdnReverb {
    character: hall,
    size:       0.6,
    brightness: 0.5,
    pre_delay:  0.3,
    mix:        0.8
}

Parameters

Character archetypes

Inputs

Outputs

Convolution reverb (external bundle)

ConvReverb and StereoConvReverb are not part of the in-tree patches-modules crate. They ship from the external patches-fft-bundle and are loaded at runtime by the plugin scanner — see Implementing a native plugin for how host-loaded bundles work.

Dynamics

Source of truth: the doc comments on each module struct in patches-modules/src/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

Limiter — Lookahead peak limiter

Transparent peak limiter with true lookahead. The attack_ms parameter determines how far ahead the detector looks, giving the gain envelope time to ramp down before a transient arrives at the output — eliminating the overshoot that zero-latency limiters suffer.

Inter-sample peaks (peaks that fall between base-rate samples) are caught by internally upsampling the detector path to 2× rate. The extra precision prevents hard-clipped peaks from sneaking through at high signal levels.

The output is hard-clipped to ±1.0 as a final safety stage.

Signal chain (per base-rate sample)

input ──► dry delay (lookahead + group delay)
      │
      └─► 2× interpolator
              │
              ▼
           peak window [t-L .. t]
              │
              ▼
           gain computation (attack / release smoothing)
              │
              ▼
           output = clamp(delayed_input × gain, −1.0, 1.0)

Parameters

Inputs

Outputs

Notes

• The module introduces a latency of attack_ms plus a small FIR group delay (~8 samples at base rate for the interpolator). Account for this when mixing a limited signal against an unlimitated reference.
• All buffers are pre-allocated at prepare time for the maximum attack_ms value (50 ms), so changing attack_ms at runtime never allocates.

StereoLimiter — Stereo lookahead limiter

Stereo variant of Limiter with linked gain reduction across channels. See patches-modules/src/stereo_limiter.rs for the current parameter set.

Compressor — Feed-forward compressor

Feed-forward compressor with soft knee, peak / RMS detection, and a sidechain input. When sidechain is unconnected the detector self-keys from in (the standard hardware default — see ADR 0076).

The static gain curve is C¹-continuous across the knee region: at the boundaries threshold ± knee_width/2 both value and slope match the linear / no-reduction branches, so the knee introduces no kink. A high ratio value asymptotically approaches a limiter shape; no special casing of ratio = ∞ is required.

Parameters

Inputs

Outputs

StereoCompressor — True-stereo feed-forward compressor

Stereo variant of Compressor with linked detection: a single magnitude derived from both channels drives one detector, and one gain reduction value is applied identically to L and R. This preserves the stereo image under asymmetric transients (a per-channel detector would shift the image on panned hits).

Detector magnitude:

• Peak: max(|L|, |R|)
• RMS: sqrt((L² + R²) / 2)

Parameters are identical to Compressor. The sidechain port is stereo; a mono source patched in is broadcast to both channels per ADR 0059.

Inputs

Outputs

Gate — Threshold gate with hysteresis

Threshold gate with hysteresis, attack / hold / release ballistics, and a sidechain input. The detector self-keys from in when sidechain is unconnected (ADR 0076). Gating is binary in intent — there is no mix parameter; a patch author wanting ducking-with-blend uses Compressor with high ratio and mix < 1.

The gate opens when the rectified detector key crosses threshold (the fire condition is armed && |x| > threshold — the threshold itself, not threshold - hysteresis). Hysteresis controls eligibility: after a fire the state machine disarms and only re-arms once the signal has dropped below threshold - hysteresis. Once open the gate cannot close for at least hold ms; after that it closes when the signal drops below threshold - hysteresis. Attack and release set the ramp times of the open/closed envelope.

Parameters

Inputs

Outputs

StereoGate — True-stereo threshold gate

Stereo variant of Gate with linked detection: one detector is fed by max(|L|, |R|) and one gate state drives both channels. This preserves the stereo image — per-channel detection would cause audible image shift on asymmetric transients.

Parameters are identical to Gate. The sidechain port is stereo; a mono source patched in is broadcast to both channels per ADR 0059.

Inputs

Outputs

Bitcrusher — Bit-depth and sample-rate reduction

Quantises samples to a configurable bit depth and decimates the sample rate. See patches-modules/src/bitcrusher.rs.

Drive — Nonlinear waveshaper

Soft-clip saturation / overdrive. See patches-modules/src/drive.rs.

TransientShaper — Attack/sustain emphasis

Envelope-follower-based transient emphasis and suppression. See patches-modules/src/transient_shaper.rs.

Detectors

Source of truth: the doc comments on each module struct in patches-modules/src/detectors/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

The detector family converts an audio signal into control events or sustained gates by threshold-crossing the instantaneous signed sample value — not envelope, magnitude, or onset. Two sub-families share a threshold + hysteresis state machine but differ in what they emit:

• Trigger family (AudioToTrigger, PolyAudioToTrigger) emits ADR 0047 sub-sample sync events on a Trigger cable. Intended for clock recovery from oscillator-rate audio, sub-octave division (a divider chain fed by an AudioToTrigger cascade), and driving hard-sync ports from an arbitrary audio source.
• Gate family (AudioToGate, PolyAudioToGate) emits sample- accurate sustained gates (0.0 / 1.0) on a normal mono / poly cable. Intended for sustained-state derivation from a signed-sample stream — the schmitt-trigger pattern.

Onset / transient detection (envelope follower → threshold) is a different problem and not provided here.

AudioToTrigger — Mono threshold-crossing detector

Fires a sub-sample sync event when the input crosses threshold in the chosen direction. The event fraction is the linear-interpolated zero-crossing position inside the current sample interval: frac = (threshold - prev) / (curr - prev), encoded on the output Trigger cable per ADR 0047.

Hysteresis is a two-state machine. After a rising fire the detector disarms; it only re-arms once the signal drops below threshold - hysteresis. Hysteresis controls eligibility, not event location — the fire point is threshold, never threshold - hysteresis. The falling direction is symmetric.

Bidirectional detection tracks the rising and falling arm states independently.

Parameters

Inputs

Outputs

PolyAudioToTrigger — Per-voice threshold-crossing detector

Polyphonic variant. One independent EdgeDetector runs per voice channel, so per-voice transitions fire on the corresponding lane of the output PolyTrigger cable. Parameters apply identically across voices.

Inputs

Outputs

Parameters identical to AudioToTrigger.

AudioToGate — Mono Schmitt-trigger gate

Holds a sustained gate high while signal > threshold; closes the gate when signal < threshold - hysteresis. Values inside the schmitt band hold the previous state. Sample-accurate per ADR 0030 — no sub-sample reporting.

Parameters

Inputs

Outputs

PolyAudioToGate — Per-voice Schmitt-trigger gate

Polyphonic variant. One independent GateSchmitt runs per voice channel, so per-voice gate states are emitted on the lanes of the output poly cable. Parameters apply identically across voices.

Inputs

Outputs

Parameters identical to AudioToGate.

No stereo variants

Neither family has a stereo variant. Both threshold-cross the signed sample value, and there is no consistent collapse of two signed streams into one: (L + R) / 2 cancels antiphase content; max(|L|, |R|) is rectified magnitude (contradicting the mono variants’ signed semantics — a max(|L|, |R|) gate would behave as an envelope-above-threshold detector, a different operation from the mono AudioToGate); and per-channel detection contradicts a single output. A patch needing a stereo-bus gate or trigger derives it from per-channel AudioToTrigger / AudioToGate instances fed by StereoSplitter, or from a dedicated stereo magnitude-summariser (peak / RMS) whose mono output keys an AudioToGate when envelope semantics are wanted. See ADR 0076.

Stereo utilities

Source of truth: the doc comments on each module struct in patches-modules/src/stereo/ define the canonical port names, parameter ranges, and behaviour. This page is kept in sync with those comments.

The stereo utility group covers image control — pan, balance, width, mid-side encode/decode, and a sum-mono-bass crossover. StereoSplitter, StereoJoiner, and StereoSum complement these but live elsewhere today; they will migrate into this group under the source-tree reorganisation tickets.

Pan — Equal-power mono pan

Places a mono signal in the stereo field using the equal-power law (L, R) = in · (cos θ, sin θ) with θ = (pan + 1) · π/4. The total power L² + R² is preserved across the sweep; at the centre each channel receives in / √2 (−3 dB). The CV input is added to the parameter and clamped to [-1, 1] before the angle is computed.

Parameters

Inputs

Outputs

Balance — Linear stereo balance

Attenuates one side of a stereo signal while the other passes unchanged. With balance ∈ [-1, 1], gain_L = clamp(1 − balance, 0, 1) and gain_R = clamp(1 + balance, 0, 1). At the centre the signal passes through unchanged; at the extremes the opposite side is silenced. The linear ramp per side matches the mixer’s pan-law ramp shape. The CV input is added to the parameter before clamping.

Parameters

Inputs