galdr/README.md

# galdr

A terminal **grid synthesizer**. Signal flows downward through a field of
single-glyph unit generators; every incoming MIDI note voices the grid (or the
columns tagged with its channel); the mix is rendered low-latency to PipeWire.
It is orca's voice — the same esoteric, spatial approach to programming, but
for making sound instead of sending events.

```
orca-rs  ──MIDI + UDP──▶  galdr  ──PipeWire──▶  speakers / stems
   compose the pattern     voice it      (spectrust -p visualizes it)
```

## The grid

Signal flows **down**: each cell takes the sample from the cell above as its
input. Glyphs are **UPPERCASE** operators. A digit `0`–`9` to the left/right is
a constant parameter; a lowercase letter `a`–`z` reads MIDI CC (`a` = CC 0).

| glyph | unit generator | left / right param |
|---|---|---|
| `O` | sine | ratio |
| `A` | saw | ratio |
| `U` | pulse | width |
| `V` | triangle | — |
| `N` | noise | — |
| `L` `H` `B` | low / high / band-pass (SVF) | cutoff / resonance |
| `E` | envelope (gated by the note) | attack / release |
| `S` | soft clip (tanh) | drive |
| `C` | hard clip | threshold |
| `F` | wavefolder | amount |
| `D` | decimate / bitcrush | rate |
| `G` | gain | amount |
| `R` | ring modulator | ratio |
| `X` | FM: sine at the note pitch, phase pushed by the cell to its **left** (and above) | — / index |
| `M` | mix — adds the cell to its **left** | — |
| `K` | control envelope: 1 at note-on, decays to a floor; no audio input | decay / floor |
| `!` | output to master | — |

`K` is the one operator whose output is a *param*: placed to the **left** of
another operator it becomes that operator's left param, scaled 0–9. `2KL5` is
a lowpass whose cutoff starts open and decays (2) to the floor, with
resonance 5. That's the 303 filter envelope.

Each `!` sums into the master, so parallel columns stack timbres or voices.
An untagged column plays on every MIDI channel.

### Params

A param cell is a digit `0`–`9` (constant), a lowercase letter `a`–`z` (a
register: MIDI CC `a` = CC 0, or set over UDP), or one of three per-note
values: `@` velocity, `^` key tracking (note number), `?` a random value rolled
at note-on. All read on the same 0–9 scale, so `@L` is velocity-to-cutoff and
`?O` detunes every hit a little differently.

### Channel tags

A base-36 glyph directly **above** a column's top operator is that column's
MIDI channel: `0`–`9`, `a`–`f` for channels 1–16 (orca's numbering). The
column then only voices notes on that channel. A `>` right of the tag makes
the channel **mono-legato**: a note that overlaps the previous one slides the
running voice to the new pitch over 60 ms without retriggering the envelopes,
the 303 slide. From orca, make the step's note length longer than the gap.

### Acid

`examples/acid.galdr`, a 303 line on channel 1:

```
...0>
...A.      saw (U for the square)
.2KL@      K sweeps the cutoff (decay 2, floor open-to-closed); accent = velocity -> resonance
...E1      short amp decay
..3S.      overdrive
...!.
```

```
1....2....      column 0 is channel 1 (a filtered saw),
A....O....      column 5 is channel 2 (a plain sine)
L....E....
E....!....
!.........
```

### The master chain

Operators placed **below** a column's `!` no longer run per voice: they
process the summed stereo master, in series, in column order. Any filter or
shaper works there, plus two master-only effects:

| glyph | effect | left / right param |
|---|---|---|
| `Z` | delay | time (0 = 100 ms … 9 = 1 s) / feedback |
| `W` | stereo chorus | rate / depth |

```
A
!
5L        lowpass on the whole mix
3Z6       then a 400 ms delay with lots of feedback
.W        then a slow chorus for width
```

Editing the grid recompiles and hot-swaps the running program without dropping
audio. There is no embedded scope — run a spectrum analyzer (e.g. `spectrust`)
on the side if you want one.

## A drum kit (one drum per MIDI channel)

A note voices every column tagged with its channel, so give each drum its own
channel and let orca pick the channel per hit. `examples/drums.galdr`:

```
.0..9....a...b.
.A..O9...N...N.
@L5.EX9.6B5.8H.
.E2..E1..E1..E0
2S...!..3S...!.
.!.......!.....
```

- **bass** (tag `0`, MIDI ch 1): saw → lowpass with the cutoff from velocity
  (`@`) and resonance 5 → envelope, release 2 → soft clip 2 → out.
- **kick** (tag `9`, ch 10): the left column is a sine into an envelope with
  no `!`, it exists only as a modulator. The `X` next to it is a sine at the
  note pitch, phase-modulated by that decaying signal with index 9: bright at
  the hit, a clean low sine a moment later. Play it a low note (C1–C2).
- **snare** (tag `a`, ch 11): noise → bandpass 6, resonance 5 → short
  envelope → soft clip 3. A mid note sets the bandpass body.
- **hats** (tag `b`, ch 12): noise → highpass 8 → envelope with release 0.
  Note length from orca is the open/closed control.

From orca, `:` with the channel glyph per drum, e.g. `:93C` for the kick,
`:a3D` snare, `:b5F` hats, `:02C` bass. With `--stems 12` each drum also has
its own `galdr.ch*` node to record.

## An orchestra (the big example)

`examples/orchestra.galdr` is ten sections on ten MIDI channels, each in a
four-column block `[left param | chain | right param | gap]`, so every digit
is a knob. It uses most of the vocabulary: velocity (`@`) into a filter and
into an FM index, key tracking (`^`), per-note random (`?`), two modulator
columns feeding `X`, registers set from orca (`k` and `z`), and a hall on the
master chain (highpass, chorus, delay with feedback from `z`).

```
.0...1...2...3...44..5...6...7...8...9..
.A...A...A2.2U...NO.1U..5U...O7..A...V..
@L2.3L3.1EX@4L1.9HE36B6.6L1..EX3^L?.kL2.
4E5.3E4..1E23E3.1E!.2E2.2E2..0E40E3.7E7.
.!..2S...2S.1S..2G..1F...!....!..!..9G..
1H...!....!..!...!...!...............!..
2W3.....................................
4Zz.....................................
```

| ch | tag | section | how |
|---|---|---|---|
| 1 | `0` | strings | saw, lowpass cutoff from velocity, slow envelope; the hall hangs under its `!` |
| 2 | `1` | low strings | saw, lowpass 3/3, soft clip |
| 3 | `2` | brass | a saw-envelope modulator column drives `X`, FM index from velocity |
| 4 | `3` | horns | narrow pulse, lowpass, soft clip |
| 5 | `4` | flute | breath noise (highpass, short env, gain) beside a sine |
| 6 | `5` | reed | pulse width 1, resonant bandpass, fold |
| 7 | `6` | clarinet | square, lowpass |
| 8 | `7` | timpani | sine-envelope modulator into `X`, long release, play C1 to C2 |
| 9 | `8` | harp | lowpass cutoff key-tracked, resonance random per pluck, pluck envelope |
| 10 | `9` | choir | triangle, lowpass cutoff from register `k`, very slow envelope |

Load it with `galdr examples/orchestra.galdr`, or over UDP with `#orchestra`
once it sits in the patches directory. `;k5` and `;z3` from orca set the choir
brightness and the hall feedback live.

## Stems

`--stems n` adds one mono PipeWire node per channel tag, `galdr.ch0` …
`galdr.ch<n-1>` (named by the tag glyph), each carrying the dry sum of that
channel's voices, sample-aligned with the master. They are not auto-connected:
patch them in a graph tool, or record them with a multitrack recorder such as
`stems`, and master the session later.

## UDP control from orca

galdr listens on UDP port 49161 (orca's `;` operator sends there). One
datagram carries one or more commands, separated by whitespace or `;`:

| command | effect |
|---|---|
| `k7` | set register `k` to 7 of 35 (base-36), read by `k` param cells |
| `*3` | bang column 3: a 5 ms gate on that column alone, no note needed (drums, plucks) |
| `@34O` | write glyph `O` at column 3, row 4 — orca patches the synth itself |
| `@34.` | clear that cell |
| `#verse` | load the patch `verse.galdr` from the patches directory |

Bangs and register sets go straight into the audio thread; grid commands are
applied by the editor and recompiled like a keystroke.

## Patches

A patch is plain text: one line per row, `.` for an empty cell, `#` lines
ignored. `galdr file.galdr` opens one and `Ctrl+S` writes it back. With no
file, galdr works on **today's** patch, `~/hometaping/<YYYY-MM-DD>.galdr`:
opened at start if it exists, written by `Ctrl+S`. That is the same dated
naming as the orca files kept in that directory, so a session's orca pattern
and its galdr voice sort together. `#name` over UDP loads
`<patches dir>/name.galdr` (`--patches` overrides the directory).

Example — a filtered saw with an envelope:

```
A        saw at the note pitch
L        lowpass, cutoff from the digit to its left...
E        ...enveloped by the note gate
!        ...to master
```

## Usage

```
galdr [--latency <frames>] [--poly <n>] [--rate <hz>] [--stems <n>]
      [--udp <port>] [--patches <dir>] [--midi-name <s>] [patch.galdr]
```

galdr creates a virtual MIDI input port named **galdr**; connect orca or any
sequencer/DAW to it. `--midi-name` connects to an existing port instead.

Keys: cursor keys move; type a glyph to place it; Backspace clears; `Ctrl+S`
saves the patch; `?` toggles help; Esc quits. Resize the grid with `(` / `)` (width) and `_` / `+` (height)
by one ruler division, or Ctrl+arrows by one cell (orca's bindings).

galdr survives a PipeWire restart: the status line shows `PIPEWIRE DOWN —
reconnecting…` and the stream comes back on its own, voices and master-chain
state intact.

Runtime deps: PipeWire and ALSA (MIDI). Built in Rust; reuses the native
PipeWire path from spectrust. `GALDR_DEBUG=<file>` appends every event that
reaches the engine, handy when orca and galdr disagree.