editor

The editor treats the score as literal syntax. Browser autocorrect, smart punctuation, and double-space periods are suppressed. Completions are suggestions only — the REPL does not silently rewrite your patch.

keyboard

Cmd-Enter evaluates the patch and rebuilds runtime state. Cmd-Shift-Enter replays the current patch without unlocking frozen random choices. Esc stops all active voices and keeps focus in the editor. Tab inserts two spaces, or accepts an open completion. Cmd/Ctrl-I toggles the I/O panel. Tapping Shift on a parameter/effect row opens a legality-scoped completion list for that row. ↑/↓/PgUp/PgDn navigate the completion menu while it is open. Enter commits only the missing characters for the selected completion token. Multi-token completion labels are guidance text, not direct insertion. Cmd-/ toggles line comments.

how to read this

Each voice is a block. The first line declares the voice (string, sine, osc, pluck, drone, noise, pulse, drum, sample, or video) and lays out one or more bars of slots. Lines below override parameters either as scalars (decay 4) or as one value per slot, aligned underneath. Bars are separated by |; rests are .; ~ sustains the previous note.

slots

A3 C#4 Bb2 F#5 — scientific pitch notation; default A4 = 440 Hz unless overridden by tuning.
>6* * * G% / >>6* * *4 / <A* * . * Bb% — pitched span starts and ends (< > << >> start; % or fixed-octave wildcard tokens like *4 end). Inside an active span, only *, ., ~, and end tokens like G% or *4 are legal.
. or - — rest. ~ — extend the previous note.
sine and osc use the same pitch notation as string, with a simpler oscillator tone for hearing modulation clearly. pluck is a short pitched body, while drone keeps a persistent per-block tone and retunes on committed leaves. noise uses * for a burst and ~ for a held texture; pulse uses * for clock/click events. drum uses k s h o t r c lane tokens (plus * wildcard), a kit row for mapping, and variance 0..1 for lane diversity.
Sample slots are bare ids from the bank: tub-xither-forge, amp-014, b3-32, snm-021, lux-007.

nesting (tuplets, subdivisions)

Wrap a group of tokens in ( ) to subdivide a single slot's time evenly across them. Nest as deep as you want.
string  A3  (C4 E4 G4)  G4  (D4 (F4 A4))
— slot 1 fits three notes (a triplet), slot 3 nests a duple inside its second half.

polyrhythms

Two voice blocks with different slot counts per bar play in parallel automatically — that's a polyrhythm.
string  A3 C4 E4 G4   (4 against)
sample  tub-xither-forge . . tub-wetair-veil . . (6 against)

parameters

force — pp p mp mf f ff fff or 0–1.
decay — seconds (0.4–8). crush — bit depth (off/0 or 4–16; lower is rougher). resolution — filter/EQ detail aperture (0–1).
pan — left center right or ±1. gain — quiet half full loud or 0–1.5.
tone — dark bright or 0–1. harm — simple pair triad rich.
octave — integer ±2. glide — positive seconds (pitched voices only). glide 60 descends then holds; glide 60 restart descends then restarts; glide 60 return descends and comes back in 60s; glide 60 return 30 (or glide 60 30) comes back in 30s. With glide present, span state persists across loop/bar resets until Evaluate or Stop.
every — 4 bars or 8 beats.
Sample-only: rate — 0.25–4 (pitch shift). start — seconds into the buffer.

directives

tempo 110 · meter 4/4 · tuning kirnberger-3 · tuning kirnberger-3 432 (tuning applies forward until the next tuning line)
evaluate mode directive while transport is running:
eval reset or eval reset keep (queue evaluate to next bar reset, keep previous tails) · eval reset cut (queue reset and cut old audio) · eval now (default immediate evaluate)

sample bank

300 one-shots, mirrored from /labs/chunk-surfer:
main_b3: b3-01 … b3-64 (64).
THE TUB: 20 named (tub-xither-forge, tub-wetair-veil, …) + ultrachunk tub-s0001 … (44).
amplifications: amp-001 … amp-064.
soundnoisemusic: snm-001 … snm-064.
lux_nova: lux-001 … lux-064.

sample selectors (wildcards, freeze, gradients)

Sample slots can be more than just a single name. Selector tokens combine three operators:

* — random pick from a pool.
! — freeze the pick (lock the random roll on the first hit).
&N — gradient over N seconds (equal-power audio crossfade between the active pair).
/ — union of pools (concrete name or wildcard).

examples:
snm-* — different random snm sample on every fire.
snm-*! — random snm sample, frozen — same one every fire.
snm-*&30 — pair (A, B) of random snm samples; over 30s, crossfade probabilistically from A to B; then advance: A := B, B := newRandom; repeat.
snm-*&30! — frozen pair (A, B); 30s of mostly-A, 30s of mostly-B, oscillating forever.
snm-*/tub-*&30 — pool is the union of snm and tub banks, gradient as above.
snm-001/tub-xither-forge — random pick between exactly these two.
* alone — pool is the whole bank.

also playable from the command line

the same DSL renders to a WAV stream over SSH. pipe it into your local audio player and the patch you're typing here plays through your shell:

ssh ssh.cbassuarez.com repl < patch.txt | mpv -
ssh ssh.cbassuarez.com repl < patch.txt | ffplay -nodisp -autoexit -
ssh ssh.cbassuarez.com repl < patch.txt | sox -t wav - -d

you can also play a previously-shared patch by passing its hash:

ssh ssh.cbassuarez.com repl v1.H4sIAAAA… | mpv -

by default 8 bars are rendered (capped to ~30 s). pass --bars N to render more. output is 22 kHz stereo 16-bit WAV. run ssh ssh.cbassuarez.com repl --help for the full usage.

/labs/string for the underlying instrument · /colophon · /access

Parameter rows are control streams. In addition to literal values, params accept * to roll a random value when the transport reaches that operator, ~ to hold the previous resolved value, _ to reset to the parameter default, *! to roll once the first time transport reaches that operator and then lock it until re-evaluation, *~ for continuous random motion while the event is sounding, and *&N for a drifting random window over N seconds.

[evaluate] / Cmd-Enter is a hard evaluate: it reparses the editor, restarts transport, and frozen random choices may reroll. [replay] / Cmd-Shift-Enter replays transport without unlocking *!, frozen sample selectors, or frozen random param/effect states. Plain * still rerolls whenever transport reaches it.

string (*!4 *4 *4 *4) (*!4 *4 *4 *4)
      decay  (* 1 1 1)      (* 1 1 1)
      pan    (left right)   (center *)

string A3 C4 E4 G4
      pan    *  ~  *  ~
      crush  _  *  ~  _
      gain   1  ~  _  *!

Vector params resolve against flattened event leaves, so control streams also address subdivisions. For example, pan * ~ _ right can address individual notes inside (C4 E4), not only the parent beat.

Pitched voices also accept pitch wildcards. * chooses a random pitch from the default universe A2–G5, *! freezes a fully random pitch at that leaf, *4 chooses a random pitch class in octave 4, *!4 freezes a random pitch class in octave 4, A* chooses a random A octave, and A*! freezes one. Write * * for two random notes; ** is intentionally invalid. *4! is also invalid; write *!4 because ! freezes the randomized axis.

Span operators for pitched voices: >/< are local directional spans, >>/<< share one interleaved span cursor per direction. Shared leader rule: for >>, higher starts win (lower starts join but do not dethrone); for <<, lower starts win. End with G%/Bb%/C#% or fixed-octave wildcard ends like *4; if you omit an explicit end, the last * in the run closes implicitly (*1 for down spans, *8 for up spans).

string >6* * * G% | >6* * * G%
gain 0.55

string >>6* * * C% | >>6* * * C%
glide 0.12
pan   *~

string   *   (* *)   *   *     |   *   *   (* * *)   *!
      string   *3  (*3! *3) *4  *4   |   *   *   (* * *)   *!
      string   A*  (C*! E*) G*  ~    |   A3  C4  (E*! G4 B4) ~

speed is pattern-time: it changes how fast a voice block consumes its event stream. rate is sample playback-time. Use speed 2 for doubletime, speed 1/2 for halftime, speed pi/4 for an irrational relation, speed * for random musical speed, speed *! for frozen random speed, speed *&8 for an eight-second drift, and speed (2 1 0.5 1) for a nested speed stream. Do not write phrase-level *2; * already means wildcard in this REPL.

string   (*!4 *4 *4 *4) (*!4 *4 *4 *4) (*!4 *4 *4 *4) (*!4 *4 *4 *4)
      speed    (2 1 1/2 pi/4)
      force    f    mf        p    p     |   ff   mf   p             p
      decay    (* 1 1 1) (* 1 1 1) (* 1 1 1) (* 1 1 1)
      pan      (* ~ _ right) (* ~ _ left) (* ~ _ right) (* ~ _ left)
      crush    8

attractors

attractor couples a block to a normalized bias field rather than a fixed preset. Public/world attractors include weather, quake, tide, solar, air, traffic, grid, orbit, civic, and archive. Local/internal attractors include tub, room, audience, mic, body, memory, habit, error, and feedback.

Attractors bias wildcard and control-stream choices: *, *!, *&N, random pitches, sample selectors, random speed, pan, gain, rate, start, crush, and related params. Explicit literal values still win.

tempo 96
      meter 4/4

      string   (*!4 *4 *4 *4) (*!4 *4 *4 *4) (*!4 *4 *4 *4) (*!4 *4 *4 *4)
      attractor weather.dew
      source   station KLAX
      speed    (2 1 1/2 pi/4)
      force    f    mf        p    p     |   ff   mf   p             p
      decay    (* 1 1 1) (* 1 1 1) (* 1 1 1) (* 1 1 1)
      pan      (* ~ _ right) (* ~ _ left) (* ~ _ right) (* ~ _ left)

      sample   snm-*/tub-*&30;
      attractor quake
      source   feed all_day
      gain     *
      rate     *&12
      start    *