PatchKnob Manual

Getting Started

PatchKnob is a DAW that combines a pattern sequencer and timeline with a modular patching environment. This page gets it installed, making sound, and tells you which section of the manual covers what.

Installing

On Debian or Ubuntu, install the .deb:

sudo apt install ./patchknob_<version>_amd64.deb

On Arch, install the package:

sudo pacman -U patchknob-<version>-1-x86_64.pkg.tar.zst

Either way you get a patchknob command and a desktop menu entry. To build from source instead, from the repository root:

./scripts/install-deps.sh   # installs the system packages (asks for sudo)
./scripts/build.sh          # configures and builds; binary at build-linux/PatchKnob

install-deps.sh detects Debian/Ubuntu, Fedora and Arch families and prints the generic dependency list for anything else; --dry-run shows the command without running it. build.sh takes --debug, --clean, --jobs N (the script caps parallelism by available RAM — each compile job can want about a gigabyte) and --tests. Everything else PatchKnob needs is vendored and built into the binary. The packages themselves are produced by ./packaging/build-deb.sh and ./packaging/build-arch.sh after a build, landing in dist/.

First launch and choosing an audio device

On first launch PatchKnob opens on the system default audio output at 48 kHz with a 512-frame buffer, and scans for plugins in the background. If that is not the device you want — or you need JACK, a specific card, or an input for recording — open A/V > Audio Settings... and click a backend (ALSA / JACK / PulseAudio), an output device, an input device and a buffer size; changes apply immediately and are remembered. Details, including what happens when a device disappears, are in Mixing, Recording & Setup.

If no audio device works at all, the app still starts, with audio disabled and "No audio device" shown in Audio Settings.

Making a first sound

1. Track > Add Instrument Track adds a lane to the arrange view. A track is just routing — it has no built-in sound.
2. Open the patchbay with View > Patchbay (bottom dock), right-click the empty canvas and add an instrument: Add Sampler (the built-in keyzone sampler), Add Instrument (a VST plugin), Add Modular (Rack), Add Pure Data or Add Csound.
3. Back in the arrange view, the track header's instrument dropdown lists every playable node in the patcher. Pick the one you added — PatchKnob wires its MIDI and audio for you, and the track's mixer strip comes alive.
4. Draw a clip on the lane and open it in the piano roll or tracker to enter notes, or arm the track and record — see arrangement, note editors and recording. Press Play on the transport bar to hear it.

A short tour

The menu bar runs File, Edit, Track, Generate, Options, View, A/V, Help; the transport strip sits with it at the top, and everything else is a window or dock over the Arrange workspace.

• Arrange — the timeline: lanes, clips, fades, editing. Covered in Arrangement & Editing.
• Piano roll and Tracker — the two note editors, opened on a clip. Covered in the note editors section.
• Sample Editor and Sampler — waveform editing and the keyzone sampler instrument. Covered in the sampler section.
• Patchbay (View > Patchbay) — the modular graph: instruments, effects, MIDI ports, mixers, Rack, Pure Data and Csound nodes, and every cable between them. Covered in the patching section.
• Master Mixer (View > Master Mixer), the transport, recording, audio/MIDI setup, projects and preferences — all in Mixing, Recording & Setup.
• Generate — ask Claude for a whole arrangement, or use its panels in the piano roll, automation editor and Csound editor. Covered in The Claude Assistant.
• The View menu also switches the main workspace between Arrange, Browse (the sample and plugin browser), Auto (automation), KeyFlw and Wave.

Projects save to single .s24 files with all audio embedded (File > Save); undo is Ctrl+Z everywhere. The theme is View > Light / Midnight.

Arrangement & Editing

The arrange view is PatchKnob's timeline: one lane per track, with clips — MIDI patterns, audio regions and automation blocks — placed along a bar ruler. Everything you do to a song's structure happens here: placing, moving, trimming, splitting and consolidating clips, fading audio, and selecting material for the editors and the transport to act on.

The arrange view at a glance

The view has four fixed parts:

• The track-header column (left). One row per lane: a status spine, an INS/AUD type badge, the track name, an instrument dropdown (instrument tracks only), I/O pickers, a level meter, Mute and Solo buttons, a record-arm control and a small x that removes the track. A + row at the bottom adds tracks. Drag a header's bottom edge to resize that lane; heights are per-lane.
• The topbar (two rows above the ruler). Row A holds the edit-mode block (SHUFFLE / SLIP / SPOT / GRID), the tool strip, zoom preset buttons 1–5, the Zoom Toggle (Z<>), zoom in/out/FIT, and the vertical zoom buttons (a-/a+ for audio waveform height, m-/m+ for MIDI preview spread). Row B holds the Main/Start/End/Length counters, the GRID and NUDGE value fields, and the chips: EDIT (the command menu), VIEW (waveform and clip display options), LAY (Layered Editing), T<E (Link Timeline and Edit Selection), TRK (Link Track and Edit Selection), TAB (Tab to Transients), UNI (Universe view) and ? (the built-in key reference, also on /).
• The ruler (the time band under the topbar). Bar numbers, the L/R timeline markers and the edit-selection markers. Clicking or dragging in the time band scrubs the playhead; dragging a marker moves that boundary, and Alt-dragging slides a whole selection along the ruler.
• The canvas: the lanes themselves, a bar/beat grid that always lines up with the ruler digits, the clips, the moving playhead, and a shaded band across the lanes showing the transport's L..R loop span. A horizontal song navigator (bottom) and a vertical track navigator (right) are always present; drag their thumbs to scroll.

The Universe strip (Alt+7 or the UNI chip) is a miniature of the whole arrangement drawn under the topbar, with a frame marking what the canvas currently shows. Click or drag inside it to jump anywhere in the song; drag its bottom edge to resize the strip.

One lane can carry several clips of the same pattern, and — after splits — several independent sequences. The view groups them by lane, so what you see as "one track" may be many sequences sharing a lane key. This matters for a few commands that act per sequence rather than per lane (the loop flag, for one — see the clip loop window).

Zooming and scrolling

Ctrl + a numeric-keypad digit engages Shuttle Lock: the playhead winds forward or back at a multiple of realtime (5 = 1x, 9 = the custom speed, 50–800%, adjusted with Up/Down while shuttling). +/- flip direction; 0 or Space stops. This is transport shuttling only — the engine has no varispeed scrub path, so no audio plays at shuttle speeds.

Adding tracks

The + row at the bottom of the header column (and the shell's track menu) offers three kinds:

• Instrument Track — a MIDI lane. It gets MIDI in/out ports on the master mixer and drives one instrument node, picked from the dropdown on the header's second line. Its clips are patterns, opened in the piano roll or tracker.
• Audio Track — carries audio regions and gets audio in/out ports. Clips draw their waveform; audio arrives by recording, importing, freezing or consolidating — you do not draw audio clips by hand (except with the Pencil, which edits existing samples destructively).
• Automation Track — a lane of automation clips, each drawing its region's curve, loop repeats and a live playhead dot. An automation lane owns no mixer track of its own: it inherits the track of the nearest non-automation lane above it (or the first mapped track if there is none above). Nothing on screen says so, but it is why you add an automation lane directly under the track it should control. Double-clicking an automation clip opens the automation editor.

The per-track x removes a track. Because queued undo steps may name the deleted sequence, deleting a track clears the undo queue — make sure you mean it.

Working with clips

Creating. On an empty instrument or automation lane: double-click to place a one-pattern-length clip snapped to the grid, drag with the Pencil tool to place and grow one, or right-click for Add Piano Clip / Add Tracker Clip / Add Automation Clip. A single click on empty space just sets the paste anchor and starts a rubber-band selection, so you cannot scribble clips by accident.

Moving. Drag a clip's body. Placement follows the edit mode (snapped in Grid, free in Slip, packed against neighbours in Shuffle — see edit modes). A snapped guide line and a bar.beat readout follow every drag. Grabbing one clip of a multi-selection moves the whole group rigidly; if any lane would hit a neighbour, the whole group clamps rather than shearing apart. Dragging against a view edge auto-scrolls.

Trimming. Drag within 6 px of a clip's left or right edge (any tool), or use the Trimmer, whose whole clip body is a trim zone split at the middle. A left trim keeps the content anchored — pulling the edge in hides material, it does not drag notes or audio along. On audio, the trim edits the region non-destructively: the source audio is untouched and can be revealed again.

Slipping (audio). Alt+drag an audio clip's body slides the source material under the fixed clip window.

Splitting. Middle-click a clip at the pointer, press X to split the focused lane at the playhead, click with the scissors (Cut) tool, or use the context menu's Split. Splits land on the snapped tick. The right half of an audio split becomes a new lane-mate region; fades split with the halves (see Preserve Fades).

Duplicating. Ctrl+drag drags a ghost copy and commits it on release (a plain Ctrl+click adds to the selection instead and never duplicates). Ctrl+D duplicates the selection immediately after itself; the context menu has Duplicate too.

Deleting. Delete removes the object selection; with a range selection it clears the range; Ctrl+Delete clears all track data in the selection. Right-click > Delete removes one clip. Deleted audio clips are cached to disk so undo restores them exactly.

Renaming. Ctrl+Shift+R or right-click > Rename edits the name in place. Double-click opens the clip's editor (piano roll, sample editor, or automation editor, by clip kind).

Audio-clip affordances. Each audio clip carries a top-right loop chip (see the loop window), a lower-right extend handle (drag to lengthen the region; a looping region wraps its source to fill, and Ctrl constrains the drag to whole loop iterations), and a horizontal gain line whose centre handle drags the region gain from silence to 2x (+6 dB) with a live dB readout. The right-click menu adds Fades..., Normalize, Reverse, Mute/Unmute, Split Into Mono, Compact... (destructive — it discards unused source audio and cannot be undone), Sync Point and a 1–5 rating.

Overlaps. The LAY chip toggles Layered Editing: ON, a clip dropped over another leaves the covered clip intact underneath; OFF, the covered clip is trimmed to the overlapper on drop. Fully covered clips are removed either way.

Edit modes

One of four modes governs how every clip gesture places its result. F1–F4 select them; ` cycles.

Snap To Grid is a separate flag that combines grid snapping with Shuffle, Slip or Spot: Shift+F4 toggles it, and Shift+F1..F3 select that mode with the flag on. Ctrl-clicking the SHUFFLE button locks Shuffle out entirely (so a stray F1 cannot ripple your session); Ctrl-click again to unlock.

Edit tools

PatchKnob's four original tools are reachable on bare letters — G Grabber, R Selector, C scissors (Cut), D Pencil — and the full set lives on the function keys. Esc cycles tools (after first clearing any selection). Pressing a tool's key again, or clicking its button again, cycles its sub-modes; holding the button opens the sub-mode menu. The right-click context menu carries the tool palette across its top, so you can switch tools where the pointer already is.

The scissors (Cut) tool splits a clip at the snapped click point — one click, one split. Edit/Tool Mode Keyboard Lock (in the grid value pop-up) stops a repeated F-key from cycling sub-modes; mouse clicks still may.

Selection

There are two kinds of selection, and most commands accept either:

• The edit selection — a tick range across one or more lanes, made with the Selector. A zero-length edit selection is the insertion point. While Link Timeline and Edit Selection (T<E chip, Shift+/) is on, edit selections mirror into the transport's L/R play range, and clicking an insertion point while stopped moves the playhead.
• The object selection — whole clips, made with the Grabber: click selects one clip exclusively; Shift+click toggles whole clips in and out of a noncontiguous selection (disabled in Shuffle and Spot modes); Shift+drag — or a drag started on empty lane space — rubber-bands across lanes, with a live count of the clips inside the band. Holding Ctrl or Shift while lassoing adds to the existing selection instead of replacing it.

Ctrl+A selects every clip in the project. Esc clears the selection. Link Track and Edit Selection (TRK, Shift+T) keeps the two models pointed at the same lanes.

Tab navigation. Tab moves the insertion point to the next clip boundary, Ctrl+Tab to the previous; Shift extends the selection to the target. With the TAB chip on (Ctrl+Alt+Tab toggles it), the targets are audio transients instead of boundaries.

Selection maneuvers. P and ; move the selection up / down a lane (Shift extends it over lanes, Alt peels a lane off). Numpad +/- nudge the range (bare), its start (Alt) or its end (Ctrl). Alt+Left/Right moves the selection by its own length; Ctrl+Shift+' doubles it, Ctrl+Shift+L halves it, Ctrl+Shift+E duplicates the selected material after itself and extends the selection over both copies. Alt+Shift+5 sets the timeline to match the edit selection, Alt+Shift+6 the reverse. Ctrl+Alt+Z restores the previous selection. During playback, Down marks the selection start at the playhead and Up the end — selection on the fly.

The Start/End/Length counters in the topbar are editable: click one (or press keypad * for the Main counter) and type — . moves to the next subfield, / to the next field, +/- enter calculator mode, Enter commits. The mouse wheel over a counter steps its value.

Cut, copy, paste and the Edit menu

Ctrl+C / Ctrl+X / Ctrl+V work on whichever selection you have. A range copy captures exactly the range — clips are sliced at its boundaries — and the range length becomes the clipboard span. Paste lands at the edit insertion point (or the playhead when there is none) and overwrites the material under it, separating leftovers at the paste boundaries; in Shuffle mode it pushes later material right instead. Pasting again at the same spot steps forward by the clipboard span, so repeated pastes tile instead of stacking. A single-lane clipboard pastes onto the focused lane (the highlighted one — the lane you last touched), which is how you copy clips between tracks.

Ctrl+B clears the selection without touching the clipboard. The EDIT chip opens the full command menu: the clipboard commands, clip-gain Copy/Paste/Clear Special, Repeat to Fill Selection, Capture Clip (Ctrl+R), Separate At Selection (Ctrl+E) / On Grid / At Transients, Heal Separation (Ctrl+H), the nine Trim commands (To Selection Ctrl+T, Start/End To Insertion Alt+Shift+7/8, To Fill, To File boundaries), Quantize To Grid (Ctrl+0), Consolidate, the TCE commands, Rename, ratings (Ctrl+Alt+1..5) and the user time stamp.

Consolidate

Consolidate (Alt+Shift+3, or EDIT > Consolidate) stitches material into one new clip. It has two forms:

• Clip selection (no range): per lane, exactly the selected audio clips render — in timeline order, the gaps between them preserved as silence, each piece's gain and fade envelope baked in — into one new clip spanning first start to last end. Unselected material inside that span is neither rendered nor removed. This is the "stitch the cut pieces back into one clip" gesture: lasso the slices, consolidate.
• Range selection: each selected lane's boundaries are separated first, then everything inside the range — silence included, muted clips as silence — renders into one new whole clip replacing the range. On MIDI lanes the covered clips' played events (loops unrolled at their window's period) are flattened into one new one-shot pattern spanning the range.

The new audio clip is named "Consolidated" (MIDI results get the source name plus "cons"). The removed pieces and the new clip land in one undo entry, so a single Ctrl+Z takes it all back.

The audio mix Consolidate performs is engine code with an automated rendered-sample test covering gap placement, source offsets, gain and fade curves — but nothing in the project records a listening check of the result. Sample-accuracy is machine-verified; if a consolidated clip sounds wrong to you, undo restores the pieces exactly.

Fades and crossfades

Audio clips (including frozen ones) carry a per-clip fade-in and fade-out. The fade you see is evaluated by the same curve function the engine plays, so the drawn envelope is the audible one.

By hand. Drag a clip's top corner inward to set a fade length; drag the mid-fade point to bend a Standard or S-Curve fade. With the Smart tool, the top corners pull fades out and the zone over an existing fade reshapes it; with the Selector, Ctrl+click does the same.

From the selection. Ctrl+F creates fades from the edit selection: a selection reaching a clip's start makes a fade-in, one reaching its end a fade-out, one crossing the joint between two clips a crossfade, and one covering whole clips opens the Batch Fades dialog (fade-in/crossfade/out at typed millisecond lengths, placed pre-splice, centred or post-splice, optionally adjusting existing fades' shapes and lengths). Ctrl+F opens the Fades dialog — curve editing, shape preset thumbnails, waveform views, an Audition button that plays the fade through the real signal path, and five storable presets — while Ctrl+Win+F (or Ctrl+Alt+F, for window managers that grab the Start key) applies your default fade settings with no dialog. Win+D (or Ctrl+Alt+D) fades from the clip start to the insertion point, Win+G (or Ctrl+Alt+G) from the insertion point to the clip end — the Ctrl+Alt forms exist for desktops where the Super key is owned by the window manager. EDIT > Fade To Start / Fade To End do the same from the menu.

Shapes and slopes. Fades come in Standard, S-Curve and seven parabolic preset shapes, each with an Equal Gain or Equal Power slope; a crossfade's halves are linked Equal Power, Equal Gain, or not at all. Alt+Win+Left/Right cycles every fully selected fade through the shapes; the right-click Fades... submenu sets shape and slope directly (a ~ marker means the selection mixes values).

Crossfades. A crossfade is two lane-mates whose regions overlap — the left clip fading out and the right fading in across the overlap. The engine sums both enveloped regions, so the crossfade is heard, not just drawn. Drag the bottom seam between two adjacent audio clips with the Smart tool to create or resize one; the window clamps to the source material actually available beyond each clip's edges. Trimming or nudging a contributor re-clamps the crossfade; pushed past any possible overlap it is removed. Deleting a crossfade retracts the two regions to a butt joint at the overlap midpoint. The Overlapped Crossfades view option (VIEW chip) draws each contributor's hidden material as a ghost overlay.

Fades as objects. Clicking a fade (not its handles) with the Grabber selects it: Delete removes it, numpad +/- nudges it, and dragging slides it within its clips. EDIT > Delete Fades removes every fade the selection covers.

Preferences. Right-click a clip > Fades... > Fade Preferences...: default shapes, slopes and link for new fades and crossfades, audition pre/post-roll, AutoFades (0–10 ms of automatic micro-fade applied by the player at every clip boundary; saved with the session), Smart fade-adjust needs Ctrl, and Preserve Fades when Editing. With Preserve Fades ON (default), splitting a clip keeps the fade-in on the left half and the fade-out on the right, trimmed to the new boundaries, and clips separated out of a crossfade keep their halves as plain fades; OFF, fades touched by an edit are dropped.

Fades are part of the saved region and come back with it: after a project reload every audio lane — frozen, recorded, consolidated or plain — redisplays the fade handles it had before the save.

The clip loop window

Do not confuse two loops that meet on this timeline:

• The transport loop — the L/R markers on the ruler, shown as a shaded band across the lanes. It repeats playback of a song span and belongs to the transport.
• The clip loop — each clip's own repeat flag, toggled by the chip in its top-right corner (or the context menu's Loop On / Loop Off (1-Shot)). It decides what the clip plays inside its own block, wherever that block sits.

A looping MIDI clip repeats its loop window — the [loop start, loop end) span set in the pattern editors, or the whole pattern when no window is set — at the window's period, for the clip's whole length. That is how a 3-step figure tiles polyrhythmically across a 4/4 bar. A one-shot clip plays its data once from the clip start; the dead air after the data is drawn as a hatched tail, so a one-shot and a looping clip are distinguishable at a glance. The note preview drawn on the clip mirrors exactly what the player will sound, repeats and all.

The loop flag and window live on the pattern, not on the block: every clip of the same pattern flips together when you click one chip. Splitting a MIDI clip copies the window and flag onto the new half, so both halves keep playing what they played.

Audio clips have their own version: the region's loop flag wraps the source to fill the block (the same chip position, a different mechanism). The Loop Trimmer's bottom half sets the iteration length; dragging the extend handle on a looping region fills the new span with repeats, and the automation-clip equivalent repeats its curve on the region's own loop length.

Undo and redo

The arrange view keeps one multiple-undo queue covering every arrangement edit — clip moves and trims, deletes (audio deletes are disk-cached and restored exactly), fades, pastes, consolidates, record takes. Ctrl+Z undoes, Ctrl+Shift+Z or Ctrl+Y redoes. A compound edit (say, a delete that tears down three audio clips) unwinds as one step. When this queue has nothing left, the keys fall through to the shell's project-wide snapshot undo, so patch and mixer edits still undo with the arrange view focused. A status line names each step ("Undo: Move Clip", "Can't Undo").

U opens the Undo History window: the queue as a list with creation times, done steps bold, and an Options pop-up (show times, Undo All, Redo All, clear the queue, and the Levels of Undo setting — default 32, settable 1–64; beyond the limit the oldest step falls off). A fresh edit truncates any redo tail, as usual.

Three things empty the queue outright: loading another project, deleting a track, and Compact (which is itself destructive and warns first). Note also that bare Z is previous zoom, not undo.

Nudge, snap and the grid

The grid. The GRID field in the topbar shows the current value; S cycles it (BAR, 1/2, 1/4, 1/8 ... 1/128, OFF), Shift+= / Shift+- step it larger / smaller, and the wheel over the field does the same. The field's pop-up adds Dotted and Triplet modifiers and the time scale: Bars|Beats, Min:Secs (a wall-clock ladder from a minute down to a millisecond), Samples (one source sample), or Clips/Markers — free placement with magnetic snap to nearby clip boundaries, the L/R markers and the selection edges. Whether the grid actually bites depends on the edit mode: Grid mode always snaps, the Snap To Grid flag snaps the other modes, Slip alone is free.

Nudge. The NUDGE field has its own value ladder (same steps as the grid), a Follow Main Time Scale option, and a typed custom value (plain ticks, or Nms for milliseconds); Shift+Alt+=/- step it. With clips selected, numpad +/- nudges them by the nudge value; Alt trims their start instead, Ctrl their end, and Shift slides the contents inside the fixed boundaries. / and M nudge forward / back by the next larger nudge value. With only a range selection, the same keys nudge the range (bare), its start (Alt) or its end (Ctrl); with a fade selected they move the fade. Nudging a crossfade contributor stretches the crossfade to keep its outer edges where they were.

Ctrl+0 quantizes the selected clips' start points to the grid.

Reload note: an ordinary audio lane (one not backed by a freeze record) stores its link to its engine audio in the project file, so after a load it rebinds exactly — placement, gain, loop window and fades included. Projects saved by older versions carry no stored link; for those the loader falls back to matching the lane's clip start against the saved regions on its mixer track, to within one tick. Historically these lanes did not rebind at all — edits on a freshly loaded audio lane silently did nothing — so if a clip from a very old project ever refuses to split or trim, re-save it: the current format records the association.

Sequencing & Composition

PatchKnob gives you two editors for writing notes — a tracker and a piano roll, both editing the same pattern data — plus an automation editor for drawing parameter curves. This section covers all three, and the pattern and clip model that decides how what you write actually plays back on the timeline.

Opening an editor

Double-click a MIDI clip in the arrangement to open it in the piano roll; double-click an automation clip to open the automation editor. Right-click a clip for the full choice: Open Piano, Open Tracker, Split, Duplicate (automation clips offer Open Automation instead of the two note editors, deliberately — they hold no notes for those editors to edit).

The tracker and the piano roll are two views of the same sequence: a note entered in one appears in the other, and both share one undo history for the note data. Loop settings made in either editor (see patterns and clips) apply to the clip identically.

The tracker

The tracker renders one pattern as a vertical grid: time runs downward, one row per step, with the playhead row highlighted during playback. Each note column is a group of sub-columns:

• Note — three characters, e.g. C-4 or OFF.
• Velocity — two hex digits, 00–7F.
• FX — zero to eight four-digit hex command columns (see below).

A pattern can show 1–8 note columns. The toolbar band above the header has bracket buttons for everything you would otherwise reach by shortcut: [-]/[+] pairs for NOTE columns, FX columns, LPB, OCT (base octave) and the secondary row highlight; a LINES box showing the pattern length in rows (click it, type a number 1–4096, press Enter); and a LOOP / 1-SHOT chip in the row-number gutter that toggles clip looping — the same state the piano roll's chip shows.

Rows, LPB and pattern length

LPB (lines per beat) is the grid resolution of the view, not of the data. Valid values are 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64, 96, 128, 192, 256, 384 and 768 — every one divides the engine's fixed 768 ticks per beat exactly, so a row always lands on a whole tick (the triplet values 3, 6, 12… stay exact too). The default is 4. Changing LPB never touches the notes: a note that sits between rows at the current resolution is hidden at that resolution, and its row is marked so it cannot be lost silently. Raise the LPB to see and edit it again.

The LINES box sets the pattern length as rows × ticks-per-row. Shrinking a pattern hides the data past the new end rather than deleting it — type the old number back and the notes, their column assignments, their OFFs and their FX automation all return.

Note entry

With the cursor on a note cell, the computer keyboard is a two-octave piano: Z S X D C V G B H N J M is the lower octave (C, C#, D … B) and Q 2 W 3 E R 5 T 6 Y 7 U the upper. At the default base octave (4), Z writes C-4 (MIDI 60). The key also previews the note through the clip's instrument, sustaining until you release it. After each entry the cursor advances by the edit step (1–8 rows, default 1).

A tracker note sustains until something releases it: entering ` (backtick) on a note cell writes an explicit OFF, and striking a new note in the same column releases the previous one. Delete, . or Backspace clears the cell under the cursor (or the whole selection). On a velocity cell, hex keys (0–9, A–F) roll digits in; on an FX cell they accumulate up to four digits, left-aligned — typing 8 alone means 8000 (half scale), FFFF is full scale.

One column is one voice

Column assignment is not cosmetic. Every note remembers which column it was entered in, and the engine treats each column as a monophonic voice for every instrument type: striking a column cuts whatever that column was holding, one tick before the new note, so retriggers are deterministic. Notes moved between columns change voice allocation accordingly.

FX columns

Each note column carries its own FX command columns (Ctrl+= adds one, Ctrl+- removes one, 0–8 per note column). Click an FX column's header label to open the target menu: None, a MIDI CC number, or drill into an instrument / rack device for one of its parameters. New patterns arrive with two columns bound to CC 74 (filter cutoff, header C74) and CC 7 (channel volume, C07).

• A CC-bound column stores real control-change events inside the pattern, played through the normal engine path. The 16-bit cell value is quantised to the CC's 7 bits.
• A parameter-bound column (instrument, patch node or rack module parameter) stores full 16-bit values in a per-pattern store and fires them as the playhead crosses each row — for every active pattern on the track, not only the one currently shown.

FX bindings and values are per pattern: switching the tracker to another clip saves the current pattern's FX state and loads the other's, so automation never bleeds between patterns. Ctrl+I interpolates an FX column linearly across the selected rows.

Navigation and editing keys

Ctrl+M column mute is a real playback mute: the engine drops the muted column's note-ons at its emit funnel, and a note the column is holding when you mute is released immediately. Unmuting takes effect from the column's next note-on. The dimmed display and the silenced notes are driven by the same per-pattern flag, so they can never disagree.

The piano roll

The piano roll shows the same pattern horizontally: a bar/beat ruler on top (with the END marker and the loop window), a keyboard strip on the left (click a key to preview it), the note grid, and a data lane underneath for velocities. Six tools sit on the number keys — 1 edit, 2 draw, 3 erase, 4 select, 5 zoom, 6 pan. The toolbar's AI button slides out the Claude panel, which writes notes into the clip from a description — see the piano roll panel.

Entering and editing notes

• Click empty grid to add a note at the snap position; drag in empty grid to lasso-select.
• Click a note to select it (Ctrl-click adds to the selection); drag to move the whole selection. Drag a note's right edge to resize (Shift stretches the selection proportionally).
• Drag across the data lane to ramp velocities; V cycles what the lane shows (velocity, pitch bend, program, channel pressure, CCs).
• The wheel zooms time around the pointer; Shift+wheel scrolls vertically, Ctrl+wheel zooms row height.

Keys

The ruler: END marker and loop window

The END marker on the ruler is where the pattern's data ends — drag it to resize the pattern. The grey band on the ruler is the pattern's loop window: drag in empty ruler to select a new window (a bare click changes nothing), drag the band to move it, drag an edge to resize it. The LOOP / 1-SHOT chip at the ruler's right end toggles whether the clip loops at all — the same three keys and the same chip labels as the tracker, because both edit the one window the pattern owns.

As in the tracker, dragging END inward hides data rather than deleting it; drag it back out and the notes return.

Patterns and clips

A pattern is the container the editors edit: a list of events plus a length (the END marker). A clip is a placement of that pattern on the timeline — start tick, end tick, and a content offset saying where in the pattern's data the clip begins. All clips of one pattern share its data: edit the pattern and every placement changes. Placing, trimming, splitting and fading clips is section 2's territory; what follows is how the engine turns a clip into sound.

Looping clips and the loop window

By default a clip loops: it repeats its pattern for as long as the clip is, so dragging the clip longer on the timeline repeats the bars. What repeats is the pattern's loop window (loop_start–loop_end), which defaults to the whole pattern but can be any sub-region — set it from the piano roll ruler or with Ctrl+L in either editor. A 4-step window over a 1-bar pattern plays those 4 steps over and over. The window may even reach past the END marker, which is how an odd-length loop (say 3 beats) is laid over a shorter phrase: the ticks past the data play as silence, then the window wraps.

Repetitions are anchored on the clip's own left edge, not on bar 1 of the song — so a clip with a 3-step loop starts on the same step wherever you place it, and moving a clip moves its content with it.

One-shot clips

Turn looping off (the LOOP / 1-SHOT chip, or Shift+L) and the clip becomes a one-shot: its data plays exactly once from the clip's start, and dragging the clip longer just moves its end point — nothing repeats. Anything still sounding when the data reaches the END marker is released there.

Content offset

The content offset is set when a clip is split or trimmed: the right half of a split carries offset + (cut − clip start), so it carries on playing exactly where the left half stopped. But the offset means something different in the two modes, and this is easy to be caught out by:

• In a looping clip, the offset is a phase: it rotates the loop window. The clip starts playing from the offset position, and the content before the offset comes back round at the tail of each repetition. The offset is folded by the window's period, so splitting a looping clip anywhere leaves every repetition intact.
• In a one-shot clip, the offset is a trim-in: content before it is skipped, nothing wraps, and an offset at or past the END marker legitimately means "this clip's content has run out" — silence. Split a one-shot past the end of its data and the right half is quiet, as it should be, rather than replaying the pattern from the top.

Notes across a loop boundary

A note still sounding when a repetition ends is cut at the boundary, not held and not re-struck — the hard cut every DAW performs at a clip or loop edge. The one exception is a note whose note-off was recorded wrapping the pattern (a key held across the loop point while recording): that pair is kept, and the next repetition releases it where the off actually sits.

Automation

Automation clips live on automation tracks in the arrangement. Double-click one to open the automation editor: a toolbar, a bar/beat ruler, and a stack of lanes, each binding one target parameter to a breakpoint curve. Values are normalised 0–1 and mapped onto the target's real range at playback. The toolbar's AI button slides out the Claude panel, which draws curves from a description — see the automation panel.

Lanes

The + toolbar button adds a lane and opens the target picker (a drilldown: node → device → parameter, or a CC number 0–127). Each lane's gutter carries its name (click to re-pick the target, F2 to rename), delete, mute, solo and bypass toggles, a colour swatch, value-axis zoom buttons, a resize grip and a reorder handle. Toolbar chips duplicate and remove the selected lane, cycle its interpolation, toggle snap and cycle the snap size (whole note down to 1/128), zoom to fit, follow the playhead, and drive the editor's own undo/redo (Ctrl+Z, Ctrl+Shift+Z or Ctrl+Y — automation history is separate from note history).

Breakpoints

• Add: click empty lane space (a click that does not move; the tick snaps, the value is where you clicked). At most one breakpoint per tick.
• Move: drag a point; drag one of several selected points to move them together. Ctrl-click toggles a point in and out of the selection; Ctrl-drag draws a marquee over points (Shift adds the box to the selection, Alt subtracts it).
• Nudge: arrow keys move selected points by a snap step horizontally or 1/64 vertically; Shift makes it fine (one tick / 1/512).
• Exact values: Enter opens numeric entry for the selected point's value and tick.
• Delete: Delete removes the selected points, or clears the selected range; Shift+Delete removes the whole lane (a structural edit, deliberately a separate gesture).

Interpolation and curve tension

Each lane has one interpolation mode, cycled with I or the toolbar chip:

• Linear (LIN) — a straight (or bent) line between neighbouring breakpoints.
• Step (STEP) — holds the left breakpoint's value across the segment, jumping at the next one: the classic sample-and-hold step sequencer shape.
• Hold (HOLD) — jumps to the right breakpoint's value immediately after the left one and holds it.

In Linear mode every segment has a tension handle at its midpoint: drag it vertically to bend the segment (−1…+1; positive bows the curve toward the start value, negative toward the end, zero is a straight line). Tension survives moving the breakpoint.

Range selections and processes

Drag in the ruler to select a tick range across all lanes, or drag in one lane to select just that lane (Shift extends, Ctrl-click a gutter adds or removes a lane from the set). With a range active, P or the toolbar's process button opens the range processes: Quantise, Humanise, Stretch, Reverse, Shift Time, Duplicate Range; Insert Time and Delete Time (ripple edits); Scale, Offset, Invert, Normalise, Clamp; Smooth, Thin, Densify; the generators LFO Fill, Ramp Fill, S-Curve Fill, Bend Curve, Step Quantise, Random Walk and Noise Fill; and the multi-lane ops Copy Shape, Mirror Lanes, Phase Offset Lanes and Average Lanes. Breakpoints outside the range are untouched (except by the ripple ops, whose whole point is moving what follows), and the random processes are deterministic — re-running one with the same settings gives the same result.

Automation clips on the timeline

An automation clip behaves like a looping note clip: its curve repeats the clip's loop window for as long as the clip is, its content offset is a trim into the curve, and the handles at the top of each lane edit the same loop window the pattern owns. The curve drawn on the arrange clip is sampled from the same data that plays, repeats included.

Automation clips carry the same loop / one-shot switch note clips have (the clip context menu's Loop On / Loop Off (1-Shot) row), saved with the project. With looping off, a clip dragged longer than its loop window plays the curve once and then holds its final value for the rest of the clip — the automation analogue of a one-shot note clip falling silent — instead of restarting the sweep. The curve drawn on the arrange clip shows the hold, not phantom repeats.

Track lanes versus automation clips

The engine holds automation in two places. An automation clip owns its lanes: they start, loop and end with the clip, in clip-local time. A track lane belongs to a mixer track and runs in absolute song time for the whole arrangement, independent of any clip. Both play back, both are saved with the project, and both are honoured when a track is frozen or bounced.

The automation editor opens two ways: double-click an automation clip in the arrangement to edit that clip's lanes, or right-click empty space on a lane and choose Track Automation to open the editor on that track's own lane set — the lanes that run in absolute song time for the whole arrangement, independent of any clip.

What can be automated

An automation lane (and a tracker FX column — they share one target inventory) can drive:

• Patch-graph node parameters — a parameter on a plugin node in the patchbay, addressed by node.
• Rack module parameters — a parameter on one module inside a rack node, denormalised into the module's real range.
• MIDI CC — controller 0–127 on the destination track's output.
• Instrument parameters — a parameter of the destination track's hosted instrument.

All four kinds reach the engine from an automation clip during playback, locate and bounce. The first two route by node and need no track; CC and instrument-parameter targets need to know which mixer track to send to — and an automation track owns none of its own (it makes no sound). So:

An automation lane inherits the mixer track of the lane above it — the nearest non-automation lane upward in the arrangement, the convention every DAW with sub-lane automation uses. Nothing on screen says this, but it decides where the lane's CCs go and which instrument's parameter list the picker shows. Put the automation lane directly under the track it should control. If nothing sits above it, the first track in the project is used.

Two timing caveats. Patch-graph and rack targets are applied at the start of the next audio block rather than at the exact scheduled tick — fine for filter sweeps, audible on very fast stepped moves at large buffer sizes. And tracker FX columns bound to parameters (as opposed to CCs) are fired from the interface thread as the playhead crosses each row, so they carry the same block-rate granularity.

Sampler & Audio Content

PatchKnob's built-in Sampler is a keyzone instrument: it maps samples onto key and velocity ranges, plays them back with per-zone envelopes, filtering and tuning, and imports whole SoundFont presets. This section covers the Sampler window, its zones, the shared sample editor, and the disk browsers that feed them. Audio clips on the arrangement timeline and the mixer are covered in their own sections.

The sampler instrument

To create a sampler, right-click empty space in the Patchbay and choose Add Sampler. The new node arrives fully wired: it gets its own MIDI channel, its own channel on the master mixer, and its own arrange lane, so it is immediately playable. To edit it, right-click the node and choose Open Sampler Editor (the same menu also offers Parameters for the raw parameter list). The editor opens in a window titled Sampler.

The engine side is an ordinary plugin instance: the sampler's parameters surface in the tracker FX picker like any other instrument's, and its volume, pan and pitch respond per note-column when driven from the tracker.

The editor window contains, left to right: a disk browser (the sample library), the zone list, the key map, the selected zone's waveform (the full sample editor, embedded in place), the per-zone inspector, the envelope editor, and the instrument's parameter sliders. The toolbar holds three buttons:

• REPLACE WAV — load a WAV file into the selected zone. Only the audio and the display name are replaced; the zone's key range, root, velocity band and playback settings survive.
• ADD ZONE — load a WAV as a new zone (full key range, root C-4 by default).
• DELETE ZONE — delete the selected zones (Del; undoable with Ctrl+Z).

Samples can also arrive by drag and drop from the library pane (see the browser) or, for SoundFont presets, from the Sample Editor window's browser (see SoundFont support).

How a note picks a zone

On note-on, the engine considers every zone whose key range covers the played note and whose velocity range covers the note's velocity, skipping zones flagged as note-off layers. The matching zones form the note's zone group, and the overlap mode of the group's nearest-root member (ties go to the earlier zone) decides what plays:

• Play all layers every zone in the group, one voice each.
• Cycle round-robins through the group, one zone per note; the position is remembered per group across notes (it is playback state, not saved with the project).
• Random picks one zone of the group at random.

A group with a single member plays that zone whatever its mode, so a conventional non-overlapping multisample behaves exactly as it always has.

A zone marked as a note-off layer is excluded from note-on triggering and instead fires when the note is released: it plays at the releasing note's pitch, at the release velocity when the note-off carries one and the note-on velocity otherwise. Where several note-off layers match, they select among themselves with the same three overlap modes. A release layer always plays itself out — its own amplitude envelope shapes it start to finish when it has one; without one, a looped layer plays once through to the end of its sample.

Known limitation: a note-off layer fires only when the note is still sounding at note-off. A one-shot zone that has already played to its end leaves nothing for the key-up to release, so no release sample fires for it.

The key map

The key map draws every zone as a rectangle on a grid of keys (horizontal) by velocity (vertical), above a keyboard strip. Selection and editing:

• Click a zone to select it. Where zones stack in velocity, the hit test honours both the key and the velocity under the pointer, so lower layers are selectable directly.
• Ctrl+click toggles a zone in and out of the selection; Shift+click in the zone list extends a range. Shift+drag on the grid is always a marquee, even when it starts over a zone; a plain drag on empty grid is a marquee too.
• Drag a zone's body to move it; drag its left/right edges to resize the key range, its top/bottom edges to resize the velocity range, and its root marker to move the root key. The nearest handle wins, so a one-key drum zone remains movable and its velocity edges stay reachable.
• Mouse wheel over the keyboard strip nudges the selected zone's root; Ctrl+wheel over the grid zooms the visible key window around the pointer (12–128 keys).
• Dropping a library file on the grid maps a new zone to the key under the pointer; dropping it on a zone row replaces that zone's audio; dropping it in the empty space under the zone list appends a zone. The highlight shown during the drag is exactly what the release will do.

Keyboard commands (with the key map focused, not the browser):

The right-click menu on a zone or the key map repeats most of these (Rename, Duplicate, Delete, Edit waveform, Set root to this key, Shrink to one key, Spread selection over keys, Fill gaps, Layer by velocity, select and display toggles, Undo/Redo).

Zones

Each zone owns: its sample, a key range (low–high), a velocity range, a root key, loop points, and a set of playback parameters. Loop on/off, reverse, gain and the source trim are baked into the audio the engine receives, so changing them re-uploads the zone's sample; everything else is an engine-side parameter and updates live while you drag.

The ZONE PARAMETERS inspector edits the engine-side set (drag to set, Shift for fine, right-click for the default):

The remaining playback switches live in the waveform pane's right-click menu: Reverse playback, Note-on layer / Note-off layer, Key follows pitch / Fixed pitch, Velocity controls volume / Fixed volume, the three overlap modes, plus two whole-map commands, Distribute zones across keys (equal key bands) and Layer zones by velocity (equal velocity bands).

• Key follows pitch / fixed pitch — with fixed pitch the zone always plays at its root pitch regardless of the key (equivalent to KEYTRACK 0).
• Velocity controls volume / fixed volume — with fixed volume every velocity plays at full level.
• Loop — a looped zone cycles between its loop points while the note is held. A looped zone with no amplitude envelope gets a short declick fade on release; one-shot zones always play to the end, as hardware samplers do. Degenerate loop points (start at or past end) turn the loop off rather than being repaired into an invented loop.

Slices. The waveform editor supports slice markers on a sampler zone (double-click the waveform to add one). Slices automatically expand into generated sibling zones: the source zone keeps the first region and each slice becomes a one-key zone on the next key up, named name [slice N]. Moving a marker rebuilds the regions but preserves any root/key/velocity edits you made to individual slices.

There is no longer a zone-count ceiling on hand editing: every zone owns a stable engine slot, so a mapping or structural edit (move, resize, add, delete) anywhere in a multi-thousand-zone imported bank reaches the engine and touches only the zone it belongs to — unchanged zones are never cleared or re-uploaded. One practical note remains: a bulk remap (spread selection, distribute across keys) over thousands of imported zones re-pushes each affected zone's audio through the engine, which takes noticeably longer than a single-zone edit but is safe and non-destructive.

Envelopes and the per-zone filter

Instrument envelopes (AMP, PIT, CUT, RES, PAN)

The envelope pane's first five tabs are instrument-wide envelopes for amplitude, pitch, cutoff, resonance and pan. Each is a freely drawable curve:

• Double-click empty canvas to add a node (a single click is deliberately harmless).
• Drag a node to move it; right-click an interior node to delete it.
• Shift+click a node to make it the sustain point (the level held until note-off); Shift+click again to clear it.
• Each segment has a small curve handle at its midpoint — drag it to bend the segment between concave and convex.

A fresh sampler is seeded with a default amplitude ADSR. Internally the curves are resampled into up to 64 linear points and handed to the engine, so what you draw is what plays (within that resolution).

Per-zone DAHDSR envelopes (Z-AMP, Z-MOD)

The last two tabs edit the selected zone's envelopes: the amplitude override and the modulation envelope, in SoundFont's six-stage form — delay, attack, hold, decay, sustain, release (times in seconds; sustain is a level). Times span 1 ms to 120 s on a logarithmic slider, which covers SoundFont's full legal range — an SF2 stage can legitimately exceed 100 seconds (8000 timecents ≈ 101.6 s), and imported values that long are preserved, not clamped. Right-click a stage slider to reset it.

By default a zone has no envelope of its own and inherits the instrument envelope; the editor says so in words rather than showing an empty curve. Dragging any stage turns the zone override on; the toggle button releases it again (stage values are kept). The modulation envelope only does something once you give it a destination via MOD>PITCH or MOD>CUTOFF in the inspector. A zone with its own amplitude envelope runs its own release from wherever its level is at note-off — the release of one voice can never leak into another.

Filter

Each zone has an optional low-pass filter (CUTOFF/RESO in the inspector). CUTOFF at the far left means no filter at all — imported SoundFont zones whose cutoff sits above audibility are normalized to "off" rather than wasting a filter on nothing.

SoundFont (SF2) import

PatchKnob reads .sf2 banks (and Vorbis-compressed .sf3) with its own parser, resolving the generator layering rules of the SF2 spec, so imported zones become ordinary sampler zones you can edit, slice and process like any other.

Browsing a bank without loading it

In either browser (the Sampler window's library or the Sample Editor window's browser), a soundfont file shows a + affordance and expands in place like a folder: click or double-click it and its presets splice in below as rows labelled [bank:program] Name. Expanding parses headers only — a few milliseconds even on an 800 MB bank — and the parse is cached, so collapsing and re-expanding is free. No sample data is read until you actually import a preset. A soundfont row is never auditioned as audio (it is not a decodable audio file).

Importing a preset

Two ways in, one import path:

• Click a preset row in the Sampler window's own library — that browser already lives inside the sampler it imports into.
• Drag a preset row out of the Sample Editor window's browser and drop it on the Sampler window.

The import is asynchronous. Decoding a preset out of a large bank can cost hundreds of milliseconds of disk on a cold cache, so the file reading and decoding run on a worker thread while the UI stays live; the status line shows progress ("Importing … 34/120 samples (28%)"). Clicking a second preset before the first finishes supersedes it — the queue has depth one and the latest click wins, so auditioning down a preset list always ends on the preset you clicked last, and a stale import can never land after you have moved on. After each import the next preset in the bank is quietly prefetched into the disk cache, so stepping down a list gets faster, not slower.

What gets imported: every zone's key and velocity range, root key, tuning (coarse/fine/scale), pan, attenuation, filter cutoff and resonance, both envelopes (volume and modulation, including their pitch/filter routing), exclusive class, loop points and loop flag. Stereo instruments — stored in SF2 as two linked mono samples — are interleaved into single stereo zones (a broken link degrades to mono rather than failing the preset). The import replaces the sampler's previous contents, and the status line reports the result: zones loaded, distinct samples interned, stereo pairs, and anything skipped.

Memory: zones are lazily materialized

Zones that reuse one recording share one immutable buffer in the engine — a 2976-zone concert grand drawing on 192 recordings holds roughly 85 MB, not the 1.3 GB per-zone copies would cost. The editor keeps only zone metadata; a zone's audio is pulled from the engine when you select that zone (to show its waveform and let you edit it). This is why a freshly imported bank uses far less memory than its file size suggests, and why selecting a zone for the first time can do a little work. Editing one zone's audio affects only that zone: the engine copies never mutate shared buffers.

Two import options live in the Sampler browser's right-click menu and apply to every preset imported afterwards: Import: preview (128 zones) caps the import for a cheap audition of a heavy bank, and Import: collapse velocity layers drops zones whose velocity range an earlier layer over the same keys already covers. The import status line reports what each option skipped.

SF2's "loop until release" mode (sampleModes 3) still imports as a plain sustained loop, and precisely this happens: an imported looping zone holds its loop through the amplitude envelope's release stage (imported zones always carry their own envelope, and a zone with its own envelope keeps looping while it releases), so the sample tail past the loop end is never played. The playback engine has no "exit the loop on release, then play the tail" mode to map sampleModes 3 onto. The import counts these zones in its status line ("loop-until-release, played as sustained loop") rather than converting them silently, and an export writes them back as ordinary loops (sampleModes 1).

SoundFont export

The engine contains a full SF2 writer aimed at two audiences at once. For everyone else, it emits a strictly conformant SF2 2.04 file: real generators for zones, key/velocity ranges, root keys, loops, tuning, pan, attenuation, filter and both envelopes, terminal records, the 46 zero frames the spec demands after each sample — so the file plays correctly in FluidSynth, Polyphone or a hardware sampler. Writing goes to a temporary file and renames on success, so a failed export can never destroy an existing bank.

For PatchKnob itself, the writer adds a private PKST chunk carrying the state that has no SF2 generator to live in: the native FX tail (gain/pan/width/drive/filters/bitcrush/downsample/noise), tracker note-column configuration, and the exact drawn envelope curves. SF2 readers are required to skip unknown chunks, so the file stays fully standard — other samplers simply ignore the extra chunk, while PatchKnob reading its own file back restores the patch exactly. A standard-only mode omits the chunk for pure interchange; drawn envelopes are then fitted to six-stage DAHDSR, and the fit reports its worst-case error so a caller can warn before writing, not after. A 24-bit option writes the SF2.04 sm24 chunk (low bytes of 24-bit samples); older readers ignore it and play the 16-bit data.

To export from inside the program, right-click the key map and choose Export SoundFont… (or Export SoundFont (24-bit)… for the sm24 variant), then pick a destination. Every zone is written with its mapping, loop, tuning, pan, attenuation, filter and per-zone envelopes; zones sharing a sample share one pool entry, and stereo zones become linked left/right halves that PatchKnob's own importer merges back into a stereo zone.

The UI path writes standard chunks only: the shell does not yet serialise the FX tail, column setup or drawn instrument envelopes into the PKST private chunk, so those do not survive an export (the per-zone DAHDSR envelopes do). A zone with no per-zone envelope exports with the SF2 default instant envelope — the instrument-wide drawn curves have no SF2 generator to live in — and the export status line counts such zones.

The sample editor

One sample editor serves the whole program: it edits anything that holds a sample — a sampler zone (embedded in the Sampler window, or via W / Edit waveform…) and the modular rack's SMPL-1 module (in the Sample Editor window, which pairs the editor with a disk browser). It edits a sampler's playback region and knows nothing about the timeline; time-stretching a clip on the arrangement is a different editor.

Display and navigation

• Bipolar min/max waveform; ST switches between one overlaid lane and two stacked L/R lanes.
• Wheel zooms at the pointer; Shift+wheel scrolls; Ctrl+wheel zooms amplitude. Home (or FIT) shows the whole file, E zooms to the selection, Left/Right scroll (fine with Shift), PgUp/PgDn page, +/- zoom.
• Four draggable markers: S (region start), E (region end), LS/LE (loop start/end). They clamp so they can never cross. Drag on empty waveform makes a selection; Esc unwinds one thing at a time — first an in-flight drag, then the selection.
• 0X toggles snapping of edits and markers to zero crossings (on by default — this is what stops clicks).
• The footer shows position, selection length, and peak/RMS of the selected span.

Operations

Operations apply to the selection, or to the whole file when there is no selection. Everything is in the right-click menu; the common ones also have keys:

Edits are destructive to the zone's working copy and undoable; the undo history is bounded (16 steps, capped at 256 MB of retained audio), so on very long recordings the oldest steps fall off first. When the editor is hosting a sampler zone, its context menu also carries the zone playback switches listed under Zones. Double-click the waveform to add a slice marker (sampler zones only); right-click a slice for Remove, Snap to zero crossing and Clear all slices (the last one asks twice).

The browser

Two disk browsers feed the samplers, sharing one design.

The Sample Editor window's browser

A plain directory list — folders first, then audio files — with a clickable path breadcrumb and a draggable divider. It lists wav, aif, aiff, flac, ogg and mp3 files, plus sf2/sf3 soundfonts (which expand in place; see above). Selecting a file with the arrow keys auditions it; Space re-auditions the current row; Enter or double-click loads it into the editor; Backspace goes up a folder; F5 rescans. Typing letters filters the list (a filter chip appears — click it or press Esc to clear). Rows are drag sources: drop a file on the editor to load it, or drop a soundfont preset row on the Sampler window to import it.

The browser and the loader now agree by construction: the listing is built from the set of formats the loader can genuinely decode. WAV keeps the native reader; aif/aiff, flac and ogg decode through the bundled libsndfile, and mp3 appears only in builds whose libsndfile found an MPEG decoder. A format this build cannot decode is simply not listed — no row exists just to fail. Everything is resampled to the engine rate with the same band-limited resampler the WAV path uses.

The Sampler window's library

The Sampler's own left-hand pane is a simpler list: folders, audio files the loader can decode (the same set the Sample Editor's browser lists) and soundfonts. Clicking an audio file previews its waveform and auditions it (click inside the preview to play from that position); clicking a preset row inside an expanded soundfont imports it immediately. Keys while the browser pane is active: Up/Down step and audition, PgUp/PgDn page, Home/End jump, Backspace parent folder, F5 rescan, Space re-audition, Enter re-select. A breadcrumb drive menu switches roots (drive letters on Windows, / elsewhere). The pane says why it is empty — an unreadable folder and a folder with no audio files report differently. Press-and-drag a row past a small threshold to pick it up and drop it on the key map, a zone row, or the zone list; an ordinary click never starts a drag.

Modular, Plugins & Sound Design

Every sound source and processor in PatchKnob lives in one place: the patch graph, a node canvas where instruments, effects, MIDI ports and mixers are wired together with cables. This is different from most DAWs: an instrument is not loaded "into a track" — it is a node in the graph, and the mixer, the sequencer and the audio device connect to it with cables like everything else. That is also why an automation target is usually a patch-node parameter: the parameters worth automating belong to the nodes in this graph, not to a slot on a mixer strip.

The patchbay (bottom dock)

The patchbay is a window docked to the bottom of the screen, visible by default. It shares the bottom dock with the Sample Editor as two tabs; View > Patchbay (bottom dock) shows or hides the whole dock. Showing or hiding the patchbay never changes what you hear — whether audio renders through the patch graph is a separate engine state, and it switches on automatically the first time you wire something into Audio Out.

Canvas navigation: the mouse wheel pans vertically, Shift+wheel pans horizontally, and Ctrl+wheel zooms around the pointer (35–250%, with a zoom read-out bottom-left). Scrollbars appear along the edges when the patch outgrows the view. Drag a node body to move it.

A new project seeds the canvas with five permanent nodes:

• Instrument out — the sequencer's MIDI source. It grows one output plug per arrange track, so each track's notes are a separate cable.
• Hardware MIDI In — the default hardware MIDI input.
• Audio Out — the audio device sink.
• Master Mixer — the singleton master mixer node (right-click > Open Mixer opens the strip view; the mixer itself is covered in the mixer section).
• Instrument Virtual MIDI Ports — a PipeWire-style virtual patch panel; right-click > Configure MIDI Ports... sets how many ins and outs it has, and wiring one of its outputs to one of its inputs stores an internal route rather than drawing a cable.

Adding nodes

Right-click empty canvas. The menu lists the node categories: Instrument, Sampler, Effect, MIDI Ports (a submenu: virtual MIDI in/out plus every hardware MIDI in and out port on the machine), Audio I/O (a submenu: Audio In, Audio Out, Mono to Stereo), Mixer, Pure Data, Modular (Rack) and Csound, followed by Add Module.... The node is created where you right-clicked.

An Instrument or Effect node is created empty — it is a plugin host with nothing loaded. Adding an Instrument immediately opens the plugin picker so you choose what it hosts; an Effect waits until you right-click it and pick Choose Plugin....

Connecting and disconnecting

Ports are drawn as discs on the node edges: inputs on the left, outputs on the right. Audio ports are filled, MIDI ports are hollow, and MIDI cables are drawn dashed so the two never look alike. To connect:

• Drag from an output port to an input port of the same kind. The target highlights when the drop would connect.
• Click-to-connect: click a node body (it lights up, "armed"), then click a second node. PatchKnob wires the first matching output→input pair for each kind the two nodes share — so one click-click links MIDI In → Instrument (MIDI), Instrument → Audio Out (audio), or both at once. Order does not matter; you can click source or sink first. Esc or clicking empty canvas cancels an armed node.
• Click a cable on empty canvas to delete it.

The engine validates every connection; a refused one (kind mismatch, a cycle, or a full fan-in) simply disappears again so the canvas always matches the real graph.

Instruments get their own mixer track

Adding any instrument-like node — Instrument, Sampler, Pure Data, Modular (Rack) or Csound — does three things at once: the engine creates a dedicated master-mixer audio track for it, wires the sequencer's MIDI and the node's audio through that track (the cables appear on canvas), and creates an arrange lane routed to it. A fresh instrument is therefore playable and mixable immediately, with its own live mixer strip; you can still reassign lanes to other instruments from the track header dropdown.

Per-node MIDI channel: every instrument-like node carries a MIDI channel filter in the engine (default omni), so several instruments hanging off one MIDI cable could each answer a different channel. The current UI does not expose the filter: which instrument a track or MIDI source drives is decided by which node the cable ends at, and PatchKnob sets new instruments to omni. Csound is the place where channels still matter — see live MIDI in Csound.

The node menu

Right-click a node for its actions. All nodes offer Remove; the rest depends on the category:

• Instrument / Effect: Load Plugin from Disk..., Choose Plugin... (the scanned-plugin picker), Open GUI (the plugin's own editor) and Parameters (the built-in panel).
• Sampler: Open Sampler Editor and Parameters (the sampler itself is documented in its own section).
• Pure Data: Open Pd Editor.
• Modular (Rack): Open Rack Editor, plus a Polyphony list (1, 2, 4, 8 or 16 voices).
• Csound: Edit CSD.
• Mixer: Open Mixer.
• A MIDI In node: choose how many virtual ports it exposes and which hardware MIDI input feeds it (or None).

The modular rack

A Modular (Rack) node hosts a small VCV-Rack-style modular patch. Its patch-graph ports track the rack's contents: each Audio Out module inside the rack becomes a stereo output port on the node, each Audio In module a stereo input port, and there is always one MIDI input, which feeds the rack's MIDI-CV modules. Right-click the node > Open Rack Editor to edit it.

Adding modules and wiring

Right-click empty rack canvas (or just click, when the rack is empty — it says so) to open the module palette: a searchable list of module cards with a category filter at the top. Type to filter by name, slug or category, and drag a card onto the canvas to place the module. Esc or right-click closes the palette.

Wiring works like the patchbay: drag from an output jack to an input jack, or click an output jack (it arms) and then click an input jack. Right-click a cable to remove it. Right-click a module for Duplicate and Delete; Delete or Backspace removes the selected module. Knobs are dragged vertically (panels with a value display show the parameter's value while you turn it). Cables are colored per-connection so parallel runs stay readable.

What ships

The built-in set follows VCV conventions (±5 V audio, ±10 V CV, 0/10 V gates, 1 V/octave pitch), so modules interoperate the way Rack users expect. It includes:

• The core voice modules — VCO, VCF, VCA, ADSR, LFO, Mixer, 8vert, Merge, Split, Sum, Mid/Side, Octave, VCA-2, VCA Mix, Mutes, Pulses, Random, SEQ-3, sequential switches — built from the VCV Fundamental DSP through a GUI-free bridge, plus Noise, Audio In/Out and MIDI-CV.
• Native translations of Cardinal modules (currently the Befaco ATTE and ABC utilities; the original source stays vendored under vendor/Cardinal).
• A second utility set: Clock, Clock Div, a 16×16 step sequencer, S&H, Quantizer, Attenuverter, Slew, Multiple, Delay, Waveshaper, Wavefolder, Ring Mod, Panner, Crossfader, Comparator, AD Envelope, LFO2 and more.
• PatchKnob originals: the 303 Oscillator, 303 Sequencer and three Acid 303 filter variants, VCO-4 SSE, ZDF Multi, Z-Plane Filter, Harmonic Forge, Env-8 Tempo, Buffer Retrig, and a Sampler module (right-click it for Edit Sample / Load Sample...).
• The CDP processes as rack modules, under a CDP category.
• Two Scripting modules, Csound and Pd, which run a .csd or .pd inside the rack. Their jacks and knobs are declared in the script itself (chnget "jack-N" / "knob-N" channels in Csound; adc~/dac~ and [r knob-N] in Pd). Right-click one for Edit DSP (the Csound or Pd editor bound to that module) and Edit Panel (drag and resize its faceplate controls).

PatchKnob also scans a modules/ directory next to the executable for externally built bridge modules and registers whatever it finds there.

Polyphony

A rack is monophonic by default. Right-click the rack node in the patchbay and pick a Polyphony of 2, 4, 8 or 16: incoming notes are then allocated across voices and the MIDI-CV pitch/gate/velocity outputs become polyphonic signals of that width (VCV-style), so a chain of poly-capable modules plays chords. The scripting Csound module understands this too and runs one instrument instance per voice.

Csound nodes

A Csound node runs a complete .csd document inside the patch graph, compiled by a real embedded Csound. Right-click the node > Edit CSD opens the editor.

The editor and compiling

The editor is a plain text editor with the usual keys (Ctrl+C/X/V/A, undo with Ctrl+Z). The status bar along the bottom holds OPEN, SAVE and SAVE AS buttons for .csd files on disk, and a COMPILE button; Ctrl+E compiles too. The compile result lands in the same status bar: dimmed "compiled OK" text on success, the compiler's error highlighted on failure. A successful compile also re-mirrors the node's ports, because the CSD header decides them: nchnls sets the outputs (one stereo port per pair) and nchnls_i the inputs. Recompiling never glitches the audio thread — the old engine keeps running until the new one is ready.

A fresh node compiles immediately with this starter document:

<CsoundSynthesizer>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 2
nchnls_i = 2
0dbfs = 1

instr 1
endin

</CsInstruments>
<CsScore>
f 0 86400
</CsScore>
</CsoundSynthesizer>

Live MIDI: how the host drives your instrument

PatchKnob feeds the node's midi in port straight into Csound's realtime MIDI input, so instruments are triggered the classic Csound way, by live events rather than score lines:

• massign <channel>, <instr> routes a MIDI channel to an instrument. Take pitch with icps cpsmidi and velocity with iamp ampmidi 0.5.
• Use MIDI-aware envelopes — madsr / mxadsr — so the voice responds to note-off and releases instead of cutting.
• The score's f 0 86400 line is the keep-alive: it holds the performance open for 24 hours so a MIDI instrument or effect has time to run. Delete it and the performance ends immediately — the node goes silent until the next compile.

The channel-stealing trap: massign 0, N claims every MIDI channel for instrument N. With two or more instruments in one CSD, a later massign 0 silently takes the earlier instrument's input — the last one wins and nothing warns you. Give each instrument its own channel (massign 1, 1 / massign 2, 2) as soon as there is more than one.

For effects, read the node's audio inputs with ins (stereo) or inch. If you forget to declare nchnls_i, PatchKnob infers it from the in/ins/inch opcodes it finds in the orchestra and injects it at compile time, so those opcodes produce input jacks instead of silently reading nothing. The node also has a midi out port: whatever the orchestra sends with midiout is published there, sample-accurately, for wiring to a hardware MIDI output or another node.

Csound is an optional build dependency. If it was not found when this binary was built, Csound nodes still exist and load in projects, but compiling reports "Csound support was not built into this binary" and the node produces silence. The assistant's compile check is skipped (it says so) rather than failing.

The reference manual drawer

The small tab at the editor's top-right corner (marked >) slides out the complete Csound Reference Manual as a browsable drawer. It has BACK and HOME buttons, a find-in-page box (Ctrl+F focuses it; F3 or Ctrl+G steps through matches, with Shift going backwards, and the box shows a match counter), and ordinary links — click an opcode reference to follow it. Text can be selected and copied with Ctrl+C, and the drawer's left edge drags to resize. This is the same manual the assistant validates opcodes against: its index of about 1,720 opcode signatures is parsed from these very pages, so the documentation you read and the audit that checks generated code can never disagree.

The manual is a local mirror staged next to the executable (or in vendor/csound-manual in a source tree). If it was never fetched, the drawer says so and names the fetch script (tools/fetch_csound_manual.py) instead of showing a broken page.

The Csound assistant

Directly under the manual tab sits an AI tab (the two share the right edge; opening one closes the other). It is a chat panel that writes and fixes Csound for the document you are editing, and it does the whole job, not just the first draft:

1. Your request is sent together with the live editor buffer and the last compile error, plus facts the model must know: which instr numbers are already taken, whether the score has an f 0 keep-alive, and how massign routing stands.
2. The reply streams in; extended thinking is shown as a collapsible "thinking" block and a progress line replaces the silence while the model reasons.
3. Every fenced Csound block is audited against the shipped manual's opcode signatures — argument rates, counts, overloads.
4. Code that passes the audit is then compiled by the real Csound compiler on a throwaway instance (a bare instr block is spliced into your document first, since it is not compilable alone).
5. Audit mismatches or compiler diagnostics are fed back to the model automatically, up to four correction rounds. Superseded replies stay visible but greyed, and their code is never offered.
6. Only code that actually compiled is auto-applied to the editor — a whole document replaces the buffer, a bare instrument is inserted at the cursor — and the apply goes through the normal undo, so one Ctrl+Z takes it back. Code that never compiled is only available behind an explicit APPLY UNVERIFIED button, with the mismatches listed so you can judge it yourself.

The audit is deliberately conservative: expressions, user-defined opcodes, macros, arrays and plugin opcodes are skipped rather than guessed at, because a false complaint would train you to ignore the checker and waste a correction round. Everything it does report should be a real defect.

The panel keeps one conversation per Csound node (and per rack scripting module): open a different node and the transcript switches with it, switch back and your conversation resumes. A reply still streaming when you switch keeps going into the conversation that asked for it, and auto-apply is suppressed while that conversation is off screen, so code can never land in a document it was not written for. The rule, and its caveats, are described in one conversation per thing.

Backends. SET.. opens the settings window. The default backend is Claude Code: PatchKnob shells out to a locally installed claude executable and spends your existing subscription — no API key is held, stored or transmitted, and hitting the subscription's rate limit is reported as a calm "please wait" notice, not an error. The alternative is the Anthropic API with your own key, billed per token, for machines without Claude Code. The key field is always masked, the key is stored only in your user preferences bound to this machine and user (a key copied from another machine is refused, with the reason shown), and it is never written to a project file. Settings also pick the model — claude-opus-5 (the default; the code has to compile), claude-sonnet-5 or claude-haiku-4-5 — toggle extended thinking, and cycle the reply-token cap.

While a reply is generating, a STOP GENERATING bar sits above the composer; the worker unwinds and the panel reports "(cancelled)". When the editor holds a compile error, that bar becomes a one-click FIX THE COMPILE ERROR. NEW clears the transcript (disabled mid-generation, on purpose).

The pieces of this pipeline are individually tested — the stream decoders, the opcode audit, the compile oracle and the panel logic all have unit tests — but writing this manual we did not run a live end-to-end exchange against a real backend from the panel. If the assistant misbehaves, the settings window's backend status lines ("detected: <version>" / "Claude Code was NOT found on your PATH") are the first thing to check.

Pure Data nodes

A Pure Data node hosts an embedded Pd instance via libpd — real Pd vanilla, one private instance per node. The patch lives in the project, not as a file on disk: right-click the node > Open Pd Editor edits the node's stored patch text, and every commit reloads it live. The editor's OPEN / SAVE / SAVE AS buttons import and export ordinary .pd files when you do want them on disk.

The editor is a visual patcher: Ctrl+E toggles between EDIT and RUN mode (like Pd itself, and the current mode is shown as a badge), objects are placed from a palette organized into All / Sig~ / Ctrl / Math / MIDI / GUI / List / Array / Time / Data categories, and the GUI atoms — toggles, bangs, sliders, number boxes, radios — are drawn as live widgets you can operate in RUN mode, with their values fed to the running patch. The palette's object list is generated from the vanilla class registry, so everything placeable in Pd vanilla (including the FFT and analysis objects) is available. Records the editor does not understand — subpatches, arrays, scalars — are preserved verbatim rather than dropped, so a patch made in Pd proper round-trips safely even where it cannot be edited visually. Externals are not supported: what libpd vanilla can load is what runs.

The node's ports follow the patch: one stereo output port per dac~ channel pair, one stereo input port per adc~ pair, plus a MIDI in (feeding [notein], [ctlin], [midiin]...) and a MIDI out (carrying [noteout], [ctlout], [midiout]).

CDP processes

PatchKnob embeds the Composer's Desktop Project as a callable library: 56 processes lifted out of the original CDP8 command-line programs (blur, focus, combine, distort, extend, filter, grain, modify, spectral and more), each with its original parameters and documentation lines. They appear in two places: as rack modules (the CDP palette category), and in the CDP editor — an offline transformation patcher opened from a clip's right-click CDP... entry in the arrangement.

The clip you invoked it from arrives as a source node with a waveform strip. Right-click empty canvas to add a process from the palette (grouped as "group / name"), wire source → process → process by dragging between ports, and drag a parameter row's value to tune it — every node shows a rendered waveform of its own output, cached and recomputed only when something upstream changes. You can drop further clips from the timeline into the same graph.

The bottom strip has RENDER TO TRACK — renders the chain and places the result as a new audio track with its own mixer channel — and PREVIEW, which plays the render without committing it. Next to the buttons a read-out states the chain's honesty about realtime: spectral (phase-vocoder) processes report their analysis-window latency, and processes that need the whole file up front are marked "offline only" rather than pretending to stream.

VST2 / VST3 hosting

PatchKnob hosts 64-bit VST2 and VST3 plugins inside Instrument and Effect nodes.

Scanning and picking

At startup PatchKnob loads its plugin cache if one exists (instant) and otherwise scans the standard directories — on Linux /usr/lib/vst, /usr/local/lib/vst and ~/.vst for VST2, /usr/lib/vst3, /usr/local/lib/vst3 and ~/.vst3 for VST3; on Windows the usual Program Files VST locations — probing each candidate and writing the cache. View > Rescan Plugins forces a fresh scan. The picker (from Choose Plugin..., or automatically on a new Instrument node) lists every scanned plugin with its format tag and an I/O summary; multi-output instruments show their bus layout ("2x8" = eight stereo buses) so you can see there is more than one pair to patch. Load Plugin from Disk... probes a single file directly, and if a VST3 bundle exports several audio classes you choose the exact class rather than silently getting the first.

The plugin's editor vs. the parameter panel

Every plugin node offers two views. Parameters is PatchKnob's own panel: every parameter as a slider, always available, and the header lists the plugin's bus layout. Open GUI opens the plugin's own editor, embedded in a PatchKnob window frame when the platform allows it; a plugin with no native editor falls back to the parameter panel automatically. The same two views serve the mixer's insert slots.

Linux/Wayland: a plugin editor cannot be embedded in a Wayland session. Every Linux VST editor is an X11 window (VST3's only Linux platform type is X11 window-ID embedding; there is no Wayland type at all), and under Wayland the SDL window has no X11 id to parent into. So the editor opens as a separate top-level window (via XWayland), and PatchKnob shows a small companion frame that says so. The frame is not decoration: hiding it hides the plugin window, and closing it closes the editor. On an X11 session, and on Windows, editors embed normally.

The built-in effects

Four effects are compiled into PatchKnob and appear in the plugin picker and browser alongside scanned plugins (their "path" is a builtin:// identifier). They have no native GUI; the parameter panel gives the compressor and drum bus a dial layout of their own.

PatchKnob Compressor

A feed-forward compressor implemented from the Giannoulis/Massberg/Reiss design tutorial (JAES 2012), computing gain in the log domain and smoothing the gain-reduction curve — not a rectified envelope — so attack and release do not change with level.

The node has four inputs: the main stereo pair plus a real stereo sidechain key on inputs 3/4. Unpatched, the detector reads the main input and it behaves like an ordinary compressor; patch anything into the key and that signal drives the gain instead — kick-ducks-bass without workarounds. The key has its own shaping: the detector high-pass filters only the key (never the audio path), and SC Attack/Release smooth the key independently of the main gain timing. The soft knee eases reduction in across its width instead of switching at the threshold; lookahead delays the audio so the detector's gain lands on the transient it was computed from; stereo link derives one gain from the louder channel so a hard-panned hit cannot tug the image; and Mix blends dry signal back in for parallel ("New York") compression on one track.

PatchKnob Transient Shaper

Two envelope followers track the input at different speeds; their ratio is the transient measure, so the effect is level-independent — a ghost note gets the same treatment as an accent, which no threshold design can do. Parameters: Attack and Sustain (each a ±12 dB bipolar amount, centre = neutral), Speed (slides the follower pair between responding to individual hits and whole phrases), Output (±12 dB) and On.

PatchKnob Drum Bus

A drum-bus channel strip in the spirit of a drum buss: one control per job, in signal order. Drive is tanh-shaped soft saturation on the whole signal; Crunch is a harder distortion applied only above a 200 Hz split, for snare bite without kick mush; Damp is an output low-pass (20 kHz down to 3 kHz) to tame what drive added; Boom is a tuned resonator (Boom Freq 40–120 Hz, Boom Decay 60–600 ms) struck by the signal's own transients — generated sub-thump, so it works on material with no low end to boost; Transients is the two-envelope shaper as a single bipolar knob; and Compress is a fixed-character 4:1 soft-knee bus compressor whose threshold walks down and makeup walks up together, so the knob only ever adds density. Dry/Wet and On complete the set.

Classic Master Limiter

A native adaptation of AnClark's ClassicMasterLimiter-RE01 (GPL-3.0), keeping the original's fixed 580-sample lookahead and independent left/right gain-reduction meters. One control — Threshold, −20..0 dB — plus the two read-only meters; output is capped just under full scale.

Mixing, Recording & Setup

This section covers the parts of PatchKnob that sit around the music: the transport, the mixer, recording and punch recording, freezing tracks, choosing an audio device, MIDI routing, project files, and the preferences — including the built-in Claude assistant's settings.

The transport

The transport lives in a compact strip at the top of the main window; a larger version of the same panel opens from View > Transport (large window). Both drive the same clock, so it does not matter which one you use. From left to right the buttons are:

• To start — locate to tick 0.
• Rewind / Fast-forward — step the playhead one bar back or forward. These work while stopped; the playhead visibly moves and play resumes from wherever you put it.
• Play — start the transport. Pressing Play while already rolling (or while a count-in is running) does nothing rather than restarting.
• Stop — stop, leaving the playhead where it stopped. Play then resumes from that spot. Stop is also the punch-out and record-commit button (see Recording). Cancelling a pending count-in with Stop puts the playhead back where the count-in started.
• Record — arm or punch, depending on the record mode. The button shows a solid red field while actually capturing, flashes while armed-and-waiting, and carries a P, T or DP badge when a punch mode is active.
• To end — locate to the end of the arrangement (this understands audio-only projects, not just pattern triggers).
• Loop — toggle loop playback between the loop markers.
• Metronome — toggle the click. It is off by default. Right-click it (on the full panel) to toggle Count in (4 beats).

Below the buttons sit the meter, the SONG/LIVE chip, a large bar|beat|tick clock, and the tempo field. Click the BPM value, type a new tempo and press Enter to commit (Esc cancels; clicking elsewhere commits rather than dropping what you typed). Tempo is clamped to 20–500 BPM and fractional values survive end-to-end.

Song mode and live mode

The SONG/LIVE chip toggles the two playback models. In SONG mode (the default) the timeline gates playback: a clip sounds only where it is placed in the arrange view. In LIVE mode armed patterns loop freely, the classic pattern-jamming model. The chip is bright in SONG mode and dim in LIVE mode.

The loop braces

The left and right loop markers are the bracket handles in the arrange ruler; drag them to move them, or drag a range in the ruler with the Selector tool to set both at once. Looping itself is done inside the audio engine, sample-accurately — the transport is never seeked to loop, so loops are click-free and survive very short lengths.

The markers enforce a minimum loop window of one sixteenth note rather than refusing a short loop: pushing one brace into (or past) the other moves the other brace just far enough to keep a sixteenth-note window, so a deliberately short loop stays short instead of snapping back or ballooning to a bar.

Locate

Click or drag in the arrange ruler to move the playhead (it snaps to the grid; hold Alt for a free position). Every locate — ruler, the transport's step buttons, stop — moves both the sequencer and engine clocks together, and each locate or stop also releases every sounding note (an automatic MIDI panic), so nothing hangs.

Space is the global play/stop toggle. It is deliberately polite about focus: while you are typing in a text field the space is typed, not played; editors that use Space themselves (the sample editors' audition, the arrange shuttle) keep it; and while the tracker, piano roll or a code editor window is front-most, plain keys stay with its edit cursor. Everywhere else, Space starts or stops the transport (with count-in honoured, exactly like the Play/Stop buttons).

Count-in

With count-in enabled, Play and Record first run a four-beat click pre-roll (beat one accented), then start from where you were. The Play and Record buttons stay lit through the pre-roll. A second press during the count-in is ignored — Stop is the way out, and it returns the playhead to the point the count-in started from.

Record quantize

Three chips on the transport bar shape MIDI takes as they are committed (they are greyed out when record quantize is off):

• Quantize grid — click to cycle off → whole → half → quarter → eighth → sixteenth → thirty-second note.
• Q-Range — 0/25/50/75%. A note already within this fraction of the largest possible deviation from its grid line is left exactly as played, so only what is audibly off gets corrected. Left-click steps forward, right-click steps back.
• Swing — 50–70% in steps of 4. 50% is straight.

The mixer and master mixer

Open the master mixer from View > Master Mixer. It is a row of Ardour-style channel strips: one per track, then one aux-return strip per aux bus, a slim + AUX column, and the MASTER strip on the right. The same window also serves plain patchable Mixer nodes (right-click a Mixer module in the patchbay and choose Open Mixer — see the patching section); those show no aux machinery, because aux buses belong to the master only.

Each track strip carries, top to bottom:

• Name header — right-click for Rename, Clear Inserts, Unity Gain and (on an aux strip) Remove Bus.
• Input button — what feeds the strip.
• Processor box — the strip's insert-FX chain. Right-click for New Plugin..., bypass, remove, Move to Pre-Fader / Move to Post-Fader; drag entries to reorder. The fader is shown as its own entry in the list, so the pre/post split is visible and inserts can be dragged across it. A bypassed entry keeps its place but processes nothing.
• Aux send knobs — one per aux bus; drag for level, Ctrl+click to reset to zero, right-click for the send menu (below). The send section only exists while at least one bus does.
• Pan, Mute / Solo (with a solo-isolate LED), the gain fader (+6 dB at the top, on Ardour's fader taper) with a stereo meter, a numeric dB entry and a click-to-reset peak readout, then Output and Comments buttons.

Solo is real engine state, not a UI trick: soloing a strip implicitly mutes the others, the display distinguishes "muted by you" from "muted because something else is soloed", and solo state is saved with the project (format v18 and later). The strip menu (right-click the name header) also carries Solo Isolate, Solo Safe, Reset Peak, and Meter Type: PPM, DIN, Nordic, VU, K20, K14, K12 or Peak ballistics.

Aux buses and sends

Click the + AUX column to create a bus (you are dropped straight into naming it). Each track strip then grows a send knob for it, and an aux-return strip appears between the track strips and the master. Right-clicking a send knob opens a menu named for its destination bus with three entries: Enabled, Pre-Fader (a checkbox — post-fader is the default) and Level 0.

A post-fader send follows the strip's fader and mute — what a reverb send normally wants. A pre-fader send ignores the fader, mute and solo, which makes it usable as a headphone or monitor feed. The aux bus runs its own insert chain (always pre-fader; its "fader" is the return gain at the very end of the bus), and its output returns into the master mix. The master strip's own inserts are the mirror image: always post-fader, sitting between the mix bus and the audio device.

A disabled send remembers its level so it can be toggled back. Send levels are normalized 0–1; zero is silence, not merely quiet.

Recording

Arming a track

Click a track's record button in the arrange track header to arm it. Exactly one track holds the arm at a time (punch modes extend this — see below), and you cannot re-arm while a take is rolling. Arming an instrument track records MIDI; arming an audio track records audio.

MIDI recording

With an instrument track armed, press Record. From a standstill the transport starts at the playhead (after the count-in, if enabled) and every live event — hardware MIDI input and on-screen preview playing alike — is captured, timestamped against the transport. Press Record or Stop to end the take; the events become a clip at the record position, with record quantize applied if it is on.

Routing is strict and explicit: a track armed on a virtual MIDI input that has nothing patched into it records nothing, and the status line says so ("Armed on ... but nothing is patched into it") rather than silently producing an empty clip. There is no hidden hardware side channel — see MIDI setup.

Audio recording

With an audio track armed, Record opens a capture tap on that track's strip inlet. The tap is pre-fader and copies exactly what is patched into the track — an Audio In device module, an instrument, a rack — so fader, pan and mute are monitoring only and never bake into the take. A track whose inlet has nothing patched into it records silence, and the UI says so. The engine keeps eight independent taps, so the punch modes below can genuinely record several tracks at once.

Audio capture buffers are a fixed 120 seconds. A normal take — or a QuickPunch/TrackPunch pass — longer than that is truncated and the status line says so ("hit the 120 s capture limit"). Stop, commit, and roll again for longer material. DestructivePunch takes are bounded by the DP File Length preference instead.

Punch recording

PatchKnob implements the Pro Tools punch model. Choose the mode in the Options menu, with Ctrl+Shift+P (QuickPunch), Ctrl+Shift+T (TrackPunch) or Ctrl+Shift+D (DestructivePunch) — each toggles against Normal — or by right-clicking the transport's Record button, which opens the mode picker. Ctrl+click on Record cycles the modes.

• Normal — the plain take described above. MIDI tracks always punch in Normal mode.
• QuickPunch — works on the record-enabled audio track. Stopped, Record toggles Record Ready (the button flashes); Play starts the pass, and Record then punches in and out on the fly as often as you like. Each punch becomes its own clip, cut from one continuous background capture, so punching never drops audio.
• TrackPunch — like QuickPunch, but per track. Punch-enable any number of audio tracks (Super+click a track's record button; Ctrl+click is accepted as the same gesture because many Linux window managers grab Super+click). While rolling, each punch-enabled track's record button punches that track independently, and the transport's Record button punches all of them at once. Alt+Super+click toggles punch-enable on all audio tracks (Shift restricts that to tracks with a selected clip).
• DestructivePunch — writes each punch into the existing clip on the track, in place, with a crossfade at the in and out points; no new clips are created. A track is only eligible if it carries one continuous audio clip at unity clip gain, starting at the beginning of the timeline and at least as long as the DP file length; the menu item Options > Prepare DPE Tracks (run it with DestructivePunch already enabled, transport stopped) consolidates a track's existing material into such a clip. Trying to DP-enable an ineligible track is refused with the reason and its remedy. Each punch is committed at punch-out, without stopping the pass.

Punch clips are named after their lane with a pass and punch number (Audio 1_01-02 is the second punch of the first pass).

Record preferences

These live at the bottom of the Options menu and persist in punch_prefs.txt in the preferences directory:

• QP/TP Crossfade — the crossfade written at each punch boundary: none, 5, 10 (default), 20 or 50 ms. At "none" no crossfade is written into the edit, but a 4 ms monitor-only fade still smooths what you hear at the punch moment.
• DP File Length — the length of the destructive-punch take buffer: 1, 2, 5 (default), 10 or 25 minutes. Audio clips live in RAM (roughly 23 MB per stereo minute at 48 kHz), which is why the default is 5 rather than Pro Tools' 25.
• Transport RecordLock — on: the transport stays record-ready after a stop, so the next pass needs only Play. Off (the default): stop disarms. Its effect is suspended while DestructivePunch is active (the stored preference survives).
• Audio Track RecordLock — on (the default): track record and punch enables survive a transport stop. Off: they clear on every stop, tape-machine style.
• Mute Record-Armed Tracks While Stopped — mutes an armed track's monitoring whenever the transport is stopped, so an open microphone is not live between takes.

Freeze and bounce

Freezing renders a track's output to audio so its instrument and effects stop costing CPU. Right-click a clip in the arrange view:

• Freeze — renders just that clip's span to audio and plays the result in its place. The source pattern is song-muted, the lane is tinted, and the waveform is shown.
• Freeze Track — renders the whole lane (from its first clip to its last, including any release tail) onto a new audio lane named "name (frozen)", song-mutes the source, and disables the source track's devices to free CPU. The source lane and its clips stay in place for editing later.
• Unfreeze — the same menu entries flip to Unfreeze on a frozen lane. Unfreezing removes the rendered audio, restores the source's previous mute state and re-enables its devices. Deleting a frozen clip instead removes only the audio and leaves the source muted.

Track freezes are saved with the project: the rendered audio is embedded like any other project clip, and the frozen lane comes back after a load with its waveform and its link to the source, so Unfreeze still works.

File > Render to WAV... is the whole-mix bounce: it asks where to save (the picker remembers your last render location and name), plays the project once in real time, taps every master block, and writes a 16-bit stereo WAV. The capture length is computed from the timeline's real end — the furthest pattern or arranged clip — through the project's actual tempo map, plus a one-second tail so nothing released on the final beat is clipped.

Audio settings

Open A/V > Audio Settings.... The window is a list of clickable rows in four groups; the current choice in each group is marked with *, and selecting a row applies it immediately (the engine stops, reopens on the new setting and carries on):

• Driver Type / Backend — on Linux: ALSA, JACK, PulseAudio (PipeWire is reached through its ALSA/JACK/Pulse compatibility layers). Windows builds list ASIO, WASAPI, WDM-KS, DirectSound and MME.
• Output Device and Input Device — the input device feeds the patcher's Audio In module; when a capture device is selected the stream opens duplex, which is what audio recording taps.
• Buffer Size (latency) — 64 to 65536 frames in powers of two. 512 is the default. Smaller is lower latency and higher CPU risk; if you hear crackles, go up a step.
• Sample Rate — 22.05 to 192 kHz (48 kHz is the default). Applied like every other row: the engine stops, reopens at the new rate and re-prepares everything. If the device refuses the rate you pick, the engine falls back to a rate it can open rather than going silent — the row marked * afterwards is the rate actually running.

Choices persist in ~/.config/patchknob/audio_preferences.txt (on Windows, %APPDATA%\PatchKnob\) and are restored by name at the next launch.

If the device is lost — unplugged, or the server went away — the engine notices the stream dying and PatchKnob automatically reopens on the default output device. If you started with no working device at all, the app still runs (with audio disabled and "No audio device" in Audio Settings); fix the device and restart.

MIDI setup

MIDI I/O is patched, not configured in a dialog. Three building blocks, all of them patch modules — see the patchbay for the patcher itself:

• Hardware MIDI In — the built-in hardware input node, seeded into every new project. Its menu lists the MIDI inputs the system reports; pick one to bind the node to it.
• MIDI-in / MIDI-out port nodes — additional nodes bound to a hardware device, or acting as a pure routing point. A MIDI-out node sends whatever is patched into it to its device.
• Virtual MIDI — a bank of numbered virtual inputs (i-1, i-2…) and outputs (o-1, o-2…). This is the fabric tracks route through. Right-click the node, or open Instrument Virtual MIDI Ports, to change how many of each exist.

A track's header does not name a device. It names a virtual port. What that port carries is decided by a cable you draw in the patcher. This indirection is what lets you repatch a keyboard to a different track, or fan one keyboard out to several, without touching any track's settings — but it does mean selecting an input on a track is only half of the job.

Recording a hardware keyboard to a track

This is the one routing job that catches people out, because the track header will happily show an input that has nothing behind it. Both halves are required:

1. Patch the keyboard into a virtual input. Open the patchbay, click the Hardware MIDI In node and pick your device from its menu. Then drag a cable from its output to the Virtual MIDI node's i-1 input.
2. Point the track at that same virtual input. On the instrument track's header, open the MIDI input selector and choose i-1.
3. Give the track an instrument. Assign one from the clip's instrument list. The wiring from the track to the instrument's MIDI input is made for you; you do not patch that by hand.
4. Arm the track. Live input is monitored only on the armed track — an unarmed track is silent even when its routing is correct.
5. Record.

How to tell it worked. Once a cable reaches a virtual input, the track header stops showing a bare i-1 and shows the name of the device patched into it. That label is the check: if it still reads i-1 with no device name, nothing is patched into that port and you will record silence. Selecting an unpatched input also puts a message in the status line saying so.

Choosing an input on the track header alone routes nothing. Steps 1 and 2 are separate on purpose — the header selects a port, the cable decides what that port carries — and doing only the second is the usual reason a correctly-armed track records silence.

The same shape works in reverse for sending MIDI out: set the track's MIDI output to o-1, then patch the Virtual MIDI node's o-1 output to a MIDI-out node bound to your hardware. Routing a track's output to another track's input is also just a cable between the matching virtual ports.

Every route made this way is a real edge in the patch graph: it is visible in the patcher, and can be edited or deleted there. Cables that PatchKnob makes for you are rebuilt whenever routing changes; cables you draw yourself are yours and are left alone.

Projects

File > New / Open... / Save / Save As... Projects are single .s24 files, currently format version 23. Older versions load and are migrated (including pre-v13 files written at the old 192-PPQN resolution). Saves are atomic and flushed to disk before the old file is replaced.

A project file stores everything needed to reopen the session on another machine with no external files:

• Global state: theme (Light/Midnight), tempo, loop on/off and the loop markers, virtual MIDI port counts, and the session AutoFades length.
• Every sequence: name, routing, length, loop markers, its events with their tracker columns, per-pattern FX, and its arrange triggers.
• Per-track mixer state — gain, pan, mute, solo, sends, aux buses, insert chains with each plugin's own state blob.
• The whole patch graph: nodes (plugins, samplers, mixers, Rack, Pure Data and Csound patches with their documents), connections, and port-level wiring.
• Audio clips, embedded — the samples themselves, not paths — with each region's trim, source offset, loop period, gain, mute, and fade shapes/slopes including crossfade links.
• Automation tracks, lanes and breakpoints, and freeze relationships.

Plain audio lanes are re-linked to their clips after a load by matching each lane's clip position against the stored regions on its track, so waveforms reappear and clip edits (splits, trims, fades) work in a freshly loaded project. Loading also runs undo bookkeeping: undo history is kept as whole-project snapshots on disk, so Edit > Undo (Ctrl+Z) and Redo (Ctrl+Y or Ctrl+Shift+Z) span every kind of edit.

Preferences and the A/V menu

PatchKnob has no single modal preferences dialog. Settings live where they act: record preferences in Options (above), the theme in View > Light / Midnight, and the rest in the A/V menu:

• Audio Settings... / Video Settings... / Claude Settings... — open the respective windows.
• Fullscreen (exclusive) — also on F11 — and VSync.
• Playback redraw 60 / 30 / 15 Hz — a ceiling on animation frames during playback, for weak GPUs. Clicks and drags always repaint at full rate.
• A read-only line showing the SDL version and renderer in use, and — only when a sibling build is installed alongside — a "Restart with SDL2/SDL3..." item to relaunch the other build.

On mobile builds the View menu additionally offers a UI scale of 100, 125, 150 or 175%; desktop builds scale with the system automatically. Preferences files live in the per-user application directory (~/.config/patchknob/ and the SDL preferences path).

The Claude assistant settings

A/V > Claude Settings... (also reachable from every AI panel's settings button) configures the Claude assistant — one setting set shared by the Csound chat panel, the piano roll and automation panels, and the Generate window. Two backends:

• Claude Code (the default) runs your locally installed Claude Code CLI and spends your existing subscription. No API key is held, stored or transmitted by PatchKnob at all, and no metered credits are consumed. It only requires claude to be on your PATH; the settings row says plainly whether it was found.
• Anthropic API posts to the Messages API with your own key and bills per token — for machines without Claude Code, or if you prefer metered use.

The API key entry is masked while typing and the key is never shown again after saving. It is stored per user and per machine, in your preferences directory (the window shows the exact path), and the stored blob is bound to the machine that wrote it: copying the preferences file to another computer — or syncing your home directory — does not carry the account over. The other machine reports the key as foreign and asks for one of its own, by design; the window shows this machine's fingerprint so two machines can be told apart. The key is never written into a project file.

On Windows the binding is real encryption (DPAPI). On Linux and macOS it is obfuscation keyed to the machine identity plus a 0600 file: it stops the key travelling between machines and being read by other users, but it is not protection against someone who can already run code as you.

The window also selects the model — claude-opus-5 (the default; the generated code has to compile, so the strongest model earns its keep), claude-sonnet-5 or claude-haiku-4-5 — and toggles extended thinking (on by default) and the reply token budget.

If neither backend is usable — no claude on the PATH and no key (or, on the API side, a build without HTTPS support) — the chat panel does not break: it shows a plain notice explaining exactly what is missing and how to fix it, and sending is disabled until one backend works.

Video settings

A/V > Video Settings... configures the built-in screen recorder, which captures the PatchKnob window together with the mixer's master output — the audio is taken from the engine's master tap, so it cannot drift against the picture the way a re-recorded soundcard capture would. Rows (left-click steps a value forward, right-click back): codec, height (width follows the window), frame rate, encoder threads (1 keeps encoding off the audio thread), mixer audio on/off, and the output folder. Recording requires ffmpeg on the system; the window says so if it is not found. Start and stop recording from the chip at the right end of the transport bar; settings changed while recording apply to the next take.

The Claude Assistant

Claude is built into PatchKnob in four places: the Csound editor's chat panel, a MIDI-generation panel in the piano roll, a curve-generation panel in the automation editor, and a Generate menu that builds a whole arrangement. All four share one settings window (A/V > Claude Settings... — also on the Generate menu, and behind every panel's settings button) and one backend: either the locally installed Claude Code CLI spending your existing subscription, or the Anthropic API with your own key. If neither is available, each panel shows a plain notice saying what is missing; nothing else breaks.

They also share one design rule: a reply is validated data, not trusted prose. Notes, curves and plans come back against a JSON schema and every field is checked, clamped or dropped before anything reaches the project — with the repairs and drops counted in the transcript, never swallowed. Csound goes further: it is audited against the shipped opcode manual and compiled by the real compiler before it is applied. And every apply is one undo step: a single Ctrl+Z takes back an entire generation, however large.

The assistant is compiled into all desktop builds; the Android build omits it.

One conversation per thing

Every distinct thing the assistant edits keeps its own conversation: each note clip, each automation lane (and, separately, each lane set in multi-lane mode), each Csound node, each rack scripting module, and the song generator's plan and each of its instrument agents. Switch to a different clip and the transcript switches with it; switch back and your conversation — including a result still waiting for Apply — is exactly where you left it.

This is not cosmetic. With one shared transcript, turn two about instrument B arrives carrying turn one about instrument A, and the model edits the wrong thing. Keyed conversations make follow-ups ("same thing but slower", "now an octave down") mean what you think they mean, because the history behind them is about the thing on screen and nothing else.

Two consequences worth knowing:

• Switching away does not cancel a reply in flight. The turn keeps streaming into the conversation that asked for it, and its result is staged there — it is never applied to, or offered against, whatever is on screen now.
• File > New drops every conversation, including anything in flight: clip 12, lane 2 and node 7 in a new project are not the ones in the old one, and silently re-attaching a transcript to a different thing is worse than losing it. The Generate window also cancels its whole pipeline here, so nothing in flight can materialise into a project it was not asked about.

Two honest gaps. Transcripts live in memory only — they are not saved in the project file, and quitting loses them. And while File > New drops all conversations, File > Open... currently does not: after opening a different project, an old transcript keyed to "clip 12" will re-attach to the new project's clip 12, which is a different clip. Until that is fixed, treat cross-project conversations with suspicion.

Writing notes: the piano roll panel

The piano roll's toolbar has an AI button; it slides out a chat panel docked on the right (drag its left edge to resize). Describe a part — "a bassline that fits", "a 16-chord progression that modulates" — and the panel sends your request together with a context it gathers from the live project at that moment:

• tempo, meter, resolution, and the clip's length (an empty clip sends no length, so the model chooses one);
• the notes already in this clip and the notes every other active track plays in the same span, so "harmonise this" and "jam with this" are answered against the actual material, not in a vacuum;
• the harmonic timeline — the project's stored chord map when one exists, else a chord map detected from the material, else a detected key. A progression that modulates has no single key, and writing every part against the first one is exactly the bug this ordering prevents;
• a description of the existing material's rhythmic character — a raw note list says what was played, not what it feels like;
• and, when your own words ask for polyrhythm or cross-rhythm, the tuplet arithmetic for the project's resolution, spelled out.

The reply is parsed and validated note by note: out-of-range velocities and lengths running past the clip end are clamped and counted, unusable notes are dropped and counted, and a reply whose notes all failed is refused outright — your clip is untouched. A validated result is staged with APPLY (REPLACE) and APPLY (ADD) buttons; the highlighted default is replace when the clip was empty and add when it was not. Replace touches only notes (CC and pitch-bend events are left alone), the clip grows if the generation is longer, and the whole apply is one undo step — the panel's own UNDO button pops it too, restoring the clip length and the project chord map alongside the notes.

Transforms

The TRANSFORM menu applies named operations locally, no model involved, to the current selection (or the whole clip when nothing is selected): Transpose ±12/+7, Invert pitch, Retrograde, Augment ×2, Diminish ÷2, Displace a beat, Quantise 1/16, Humanise, and Conform to key. The model knows the same vocabulary — a request like "make it more interesting" may come back naming a transform instead of re-typing notes, and the panel runs it locally with no second round trip.

The chord map

When an applied clip carries a real progression — at least two chord spans — its detected chord map is stored on the project, so the next generation (in any clip, and in the Generate window) follows the same changes, modulations included. A thinner reading never clobbers a richer one: the new map must have at least as many spans as the one already stored, so a generated bassline cannot overwrite the 16-chord spine it was written against.

Drawing curves: the automation panel

The automation clip editor (see automation editing) has the same slide-out panel behind its AI button. Describe a movement — "open the filter over four bars and snap it shut on the last beat" — and the panel sends the tick domain, the clip length, the curve already on the selected lane, the notes on the track, and the project chord map.

A toggle in the panel header picks one of two target modes:

• LANE (the default) — the reply is one curve for the selected lane, and the model is given no parameter menu at all, so it can never route a curve to a parameter by guessing a name.
• ALL — the request carries a menu of the clip's lanes, each with its real units and range, and the model answers with indices into that menu ("lane 0 and lane 3"). An index pointing outside the menu is dropped, and the drop is shown in the transcript — never silently rerouted.

Curve values travel normalised 0..1 and are mapped onto each lane's own range exactly once, at the point where they are written. A value the model put outside the rails is clamped back and counted — a clamp means the model asked for something a real parameter cannot do, and you should see that it was caught.

Local shapes — no round trip

An obvious request is answered instantly, without the model: "a 4-bar triangle LFO on this" is built locally, as are ramps and fades, and invert / snap / flatten of the existing curve. The LFO shapes are sine, triangle, saw up, saw down, square and sample-and-hold. The model can also name a shape in its reply instead of typing out sixty-four breakpoints it would get subtly wrong; the panel builds the named shape locally before validation. Square and sample-and-hold are always applied with step interpolation, so the steps stay steps.

Apply goes through the editor's own edit path behind one undo step. Conversations are kept per lane (ALL mode is its own conversation), and the panel re-keys every frame, so a lane switch made anywhere — a click in the editor, a rebind from the arrange view — moves the transcript with it before your next send. A pending curve is only offered for Apply while the conversation that produced it is on screen.

The Generate menu: a whole song

Generate > Generate Song... opens a window with one composer box. Describe the song — genre, mood, instrumentation, whatever you would tell a collaborator — and press SEND. The work runs as a pipeline, and the project builds up as it goes rather than appearing all at once (a whole arrangement does not fit one reply, and asking for it that way used to return truncated JSON and nothing else):

1. Plan. One small request returns the plan: title, genre, tempo, key, meter, sections, and up to eight instruments — each carrying how it should be synthesised, not just a name (see below). An unusable plan is sent back for correction; the parsed plan is summarised in the transcript.
2. Skeleton. The moment the plan lands, PatchKnob creates the tracks, the Csound nodes, the MIDI wiring and the mixer strips — the full audible chain — with a small placeholder instrument on each node that compiles and makes a sound on exactly the channel and instrument number the plan assigned. You watch the arrangement appear instead of a spinner, and the project is playable from this point on.
3. Voices. One agent per instrument, each with its own conversation and worker, writes the Csound for its own node — at most four run at once. Every draft is audited against the shipped opcode manual and dry-compiled by the real Csound compiler (on a worker thread, so the UI never stalls); diagnostics go back to the agent for up to two correction rounds. A finished instrument replaces the placeholder on its node, live. One that still will not compile keeps its placeholder and is reported by name with the compiler's diagnostic — it never sinks the rest of the song.
4. Parts. One request per track writes its clip, against the plan and the harmonic spine — and against the clips the earlier parts already produced, since the context is re-gathered before each request. Notes are validated exactly as in the piano roll panel, clamps and drops counted.

The status board in the transcript tracks every instrument through writing / compiling / retrying / done. SEND becomes STOP while the pipeline runs; stopping (or a failure) leaves whatever was finished — the skeleton is already playable, so a cancelled generation is still a project, not a mess. The whole pipeline is one undo step: a single Ctrl+Z removes skeleton, instruments and clips together.

The harmonic spine works both ways: a project chord map stored earlier (say, by a progression you generated in the piano roll) outranks anything the window detects and is never overwritten; a project with no spine gets the plan's, so every later generation follows the same changes. Sending a new description runs the whole pipeline again — as a fresh set of tracks on top of what is there — and the plan conversation carries over, so a follow-up like "the same but slower and darker" is understood against the previous plan.

Two invisible guarantees exist because their absence is a silent-failure bug that actually shipped: every generated instrument is massigned by the host to exactly the channel its track plays on (whatever the model wrote, including inside a whole document returned against instructions), and the score always keeps an f 0 keep-alive. Both failures compile cleanly and play absolute silence, which is precisely why they are not left to trust.

Synthesis methods and physical models

The plan does not say "a bass"; it says how the bass is built. This is the field that decides whether the result sounds designed or generic: the same instrument name is a completely different patch depending on the method, and each method points the instrument's agent at a vetted palette of Csound opcodes that actually suit it. The methods:

A physical model additionally names what is being modelled — plucked, bowed or struck string, blown pipe, reed, brass, struck bar, plate, membrane, bell, vocal, or friction — and its agent is pointed at the matching family of waveguide and modal opcodes (wgpluck, wgbow, wgflute, wgclar, barmodel, mode, fof...), with the instruction to drive the model the way the object is actually played and let its own resonance make the timbre. Every opcode in every palette is checked against the shipped Csound manual by the test suite, so the pipeline can never drift into recommending an opcode that does not exist.

The Csound chat panel

The oldest of the four surfaces lives in the Csound editor and is documented with it: see the Csound assistant for the full audit-and-compile pipeline, auto-apply rules and backend setup. It follows the same conversation rule as everything here — one conversation per Csound node (and per rack scripting module), switching as you open different nodes.