# Unified Music Code — Synthesis Report
## Study of 12 systems → design for one browser-based (WebAudio) live-coding music language
### N8toriousAi's constraints: sovereign-language readability (plain English), d120-driven uniqueness, and — the key new constraint — NOTES ARE MICRO-AGENTS.

---

# PART 1 — THE 12 SYSTEMS

## 1. ChucK (Ge Wang, Princeton)
- **Core abstraction:** Strongly-timed, on-the-fly programming. You chain unit generators to the DAC with `=>` and advance time by chucking durations to `now`. Shreds = concurrent threads.
  ```chuck
  SinOsc s => dac; 440 => s.freq; 1::second => now;
  ```
- **Timing/concurrency:** Logical time is a writable variable. `1::second => now` suspends the shred exactly that long — sample-accurate. Concurrency = `spork ~` new shreds.
- **Sound generation:** Unit generators (UGens) chained into graphs: `SinOsc => LPF => Gain => dac`.
- **Uniquely great:** Time as a first-class value you assign to. And shreds are already note-agents: each shred owns its own timeline and dies when done.
- **Painful:** No pattern layer — everything is imperative loops; verbose for anything beyond drones and arps.

## 2. Csound (MUSIC-N lineage)
- **Core abstraction:** Orchestra defines *instruments* (opcode graphs), score lists *note events*. `i1 0 2 440 0.5` = instrument 1, start 0, dur 2, pitch 440, amp 0.5.
- **Timing/concurrency:** Score time, absolute seconds/beats. Instruments are independent instances.
- **Sound generation:** Enormous opcode library (oscillators, filters, FM, granular, physical models); k-rate (control) vs a-rate (audio) distinction.
- **Uniquely great:** The instrument/score split IS the voice/coordination split — a voice is a contract, the score only schedules births. Also k-rate vs a-rate honesty.
- **Painful:** Two-file split, 1980s syntax, zero liveness.

## 3. FAUST (GRAME)
- **Core abstraction:** Pure functional DSP. You write `process`, a signal function, using block-diagram algebra: `:` sequential, `,` parallel, `<:` split, `:>` merge, `~` recursive feedback.
  ```faust
  process = _ <: *(sqrt(1-p)), *(sqrt(p));  // stereo pan
  ```
- **Timing/concurrency:** Synchronous sample-stream; no musical time at all.
- **Sound generation:** Compiles DSP math to C++/WASM/etc. Primitives are C functions lifted to signals.
- **Uniquely great:** The five combinators express ANY patch with zero wiring. And it compiles to WebAssembly — a real path to heavy DSP in the browser via AudioWorklet.
- **Painful:** No notes, no events, no time above the sample. Hostile to musicians; brilliant for engineers.

## 4. Impromptu (Andrew Sorensen)
- **Core abstraction:** Scheme environment for live-coding music AND visuals. You write functions that schedule sound; performance = editing code live.
- **Timing/concurrency:** Temporal recursion — a function schedules its own next invocation in musical time. Callbacks in a real-time scheduler.
- **Sound generation:** Built-in audio engine + graphics (Quartz); sample playback, synthesis, algorithmic composition.
- **Uniquely great:** Temporal recursion: a pattern is a *process*, not data. And the proof that code-on-stage is a legitimate instrument (he live-coded an orchestra).
- **Painful:** Parentheses alienate non-Lispers; Mac-only legacy codebase.

## 5. SuperCollider (James McCartney)
- **Core abstraction:** Two halves: `sclang` (Smalltalk-ish OOP language) talks OSC to `scsynth` (audio server).
  ```supercollider
  SynthDef(\blip,{|freq=440| Out.ar(0,SinOsc.ar(freq)*EnvGen.kr(Env.perc))}).add;
  Synth(\blip,[\freq,660]);
  ```
- **Timing/concurrency:** Server-side timestamps and bundles; language-side threads/clocks. Patterns (`Pbind`, `Pseq`) are lazy event streams.
- **Sound generation:** UGens → SynthDefs (templates) → Synths (nodes on the server, each with its own lifecycle).
- **Uniquely great:** SynthDef/Synth is EXACTLY the note-agent model: a Synth is an independent server node — born, lives its envelope, freed. Nobody manages it centrally. Patterns as composable lazy streams is the second steal.
- **Painful:** Two languages, two processes, aged sclang syntax, brutal learning curve.

## 6. TidalCycles (Alex McLean — Haskell)
- **Core abstraction:** Patterns as pure functions of time. Mini-notation strings for rhythm: `"bd sd [hh hh]"`. Combinators transform patterns: `stack`, `cat`, `fast`, `every`, `euclid`.
  ```haskell
  d1 $ s "bd*4" # n "0 2 4" # cutoff "1200"
  ```
- **Timing/concurrency:** Cycle-based. The pattern is queried over time arcs; each query yields events. No mutable state in the pattern layer.
- **Sound generation:** Delegated to SuperDirt (samples) or synths; Tidal itself only schedules.
- **Uniquely great:** Mini-notation — the densest readable rhythm language ever made (`*` repeat, `[]` subdivide, `,` polyphony, `<>` alternate, `~` rest). And patterns-as-pure-functions: composition without state.
- **Painful:** Haskell install + syntax is a wall; cycle-thinking is alien until it clicks.

## 7. Alda (Dave Yarwood)
- **Core abstraction:** Plain-text music notation for non-programmers. `piano: c d e f`. Octaves via `o4` or `>`/`<`; durations `c4`; key signatures; chords `c/e/g`.
- **Timing/concurrency:** Sequential note stream in score time. One instrument is "current" until you switch.
- **Sound generation:** MIDI instruments via built-in synth (FluidR3 soundfont).
- **Uniquely great:** The surface readability — `piano: c d e f` is the sovereign-language ideal, and the REPL is literally called the Read-Evaluate-*Play* Loop. Proof that English-adjacent text can be the whole instrument.
- **Painful:** No live pattern manipulation, MIDI-timbre ceiling, no sound design.

## 8. LC (Nishino / Osaka — "strongly-timed, prototype-based")
- **Core abstraction:** Prototype-based OOP language where *microsounds are first-class objects* with methods — not hidden inside unit generators. LCSynth is the enclosed synthesis language.
- **Timing/concurrency:** Strongly-timed like ChucK (`now += period::second`) with lightweight concurrency; built for runtime modification of running code.
- **Sound generation:** Microsound objects with per-sample access plus batch manipulation methods; independent of the unit-generator concept.
- **Uniquely great:** Grains as objects: a note-agent can *decompose into grain-agents*. Prototype-based voices (clone a voice, tweak two params) beat class-based SynthDefs for live tweaking.
- **Painful:** Academic, near-zero ecosystem, overkill complexity for simple songs.

## 9. LilyPond
- **Core abstraction:** Text in, beautiful engraved notation out. `\relative c' { c d e f }` → PDF.
- **Timing/concurrency:** Notated time; not a performance system.
- **Sound generation:** None (MIDI export is an afterthought).
- **Uniquely great:** One lesson only, but it's load-bearing: **text is the primary artifact; rendering is a backend.** Notation, audio, and patch diagrams can all be compiled views of one source.
- **Painful:** Compile-to-PDF loop; useless on stage.

## 10. Max/MSP (Cycling '74)
- **Core abstraction:** Visual dataflow — boxes (objects) connected by patch cords. `metro` bangs, `cycle~` sings.
- **Timing/concurrency:** Two clocks, honestly separated: the scheduler (messages, millisecond-ish) and the signal vector (audio, sample-accurate).
- **Sound generation:** MSP objects process audio vectors; huge library.
- **Uniquely great:** Patching as a mental model, and the message/signal split is *honest* about control rate vs audio rate — a distinction every music system needs but most hide.
- **Painful:** Visual spaghetti at scale; text-hostile; proprietary and expensive.

## 11. Pure Data (Miller Puckette)
- **Core abstraction:** Open-source Max: same boxes-and-cords dataflow.
- **Timing/concurrency:** Same two-clock model as Max.
- **Sound generation:** Tilde objects (`osc~`, `lop~`); externals extend it.
- **Uniquely great:** Everything Max proves, openly — and the externals ecosystem proves a patch node can be a plugin boundary (a "voice" can come from anywhere).
- **Painful:** Same spaghetti, older GUI toolkit, same text-hostility.

## 12. Strudel (Felix Roos — TidalCycles in the browser)
- **Core abstraction:** JavaScript + mini-notation strings. `note("c a f e").s("sawtooth")`. Patterns are pure functions of time; the last statement is the pattern.
  ```js
  s("bd*4, [~ <sd cp>]*2, [~ hh]*4").bank("RolandTR909")
  ```
- **Timing/concurrency:** Cycle-based like Tidal; REPL queries patterns on a 50ms interval with ~100ms lookahead, schedules into WebAudio.
- **Sound generation:** WebAudio synths + sample maps loaded from URLs; SuperDirt effects reimplemented in WebAudio.
- **Uniquely great:** The whole architecture is the proof: JS host + mini-notation strings + patterns-as-functions + WebAudio output = zero-install live coding that actually works. Transpiles double-quoted strings into pattern calls via AST.
- **Painful:** Still Tidal-brained (Haskell idioms wearing a JS costume); sample-from-URL loading; block evaluation is clunky.

---

# PART 2 — SYNTHESIS: THE UNIFIED MUSIC CODE

## The central bet: notes are micro-agents

A composition is a **swarm of note-agents**. Each note is born with its own pitch, onset, duration, timbre parameters, and behavior; it lives its own lifecycle — **birth (attack) → sustain → release → death (cleanup)** — on its own clock, and no central authority touches it while it sounds. The pattern layer is the **conductor**: it decides births, never manages lives. The score is a **coordination protocol**, not a command list.

This is not a metaphor — it compiles directly:
- **ChucK's shred** per note (own timeline, dies when done)
- **SuperCollider's Synth node** per note (independent server node, self-freeing envelope)
- **WebAudio**: each note-agent owns its own small node subgraph (osc → filter → gain envelope), `start(t)` / `stop(t)` itself, disconnects on `onended`.

And coherence is Kuramoto, per N8toriousAi's Kraken system: note-agents can subscribe to a **groove field**. Each carries a phase offset; once per cycle the offsets relax toward the circular mean of the ensemble, weighted by coupling K. Swing and humanization become **emergent physics**, not a global knob. `groove tight` = high K; `groove loose` = low K; `groove off` = K=0.

## 6–8 design principles (with lineage)

1. **Notes are agents; patterns conduct.** (ChucK shreds + SuperCollider Synths + Kraken) A note is spawned with everything it needs and never touched again. The scheduler only schedules births. There is no note manager, no voice-stealing god-object — old notes finish their releases even if the pattern changed underneath them (this is what makes live-coding safe).
2. **English on the surface, density in the strings.** (Alda + Strudel/Tidal) Top-level reads like plain sentences — `bass plays …`, `pad holds …`. Rhythmic/pitch detail lives in mini-notation strings inside those sentences. Two registers, one language: readable to a newcomer, fast for a live coder.
3. **Conduct in cycles, execute in samples.** (Tidal + ChucK + WebAudio) Humans think in bars and cycles; the machine starts oscillators at sample-accurate `audioCtx.currentTime`. One clock domain at the execution edge — deliberately NOT Max's two-clock split; the scheduler bridges them with lookahead.
4. **Voices are contracts; timbres are patches.** (SuperCollider SynthDef + FAUST + Max/PD) A `voice` is a named signal-graph template — the contract a note-agent is built from. Voice bodies use a tiny functional DSP combinator set (FAUST's `: , <: :> ~` re-expressed in English/JS). The same graph IR renders as a Max/PD-style patch — code and patch are two views of one truth, edits round-trip.
5. **Groove is phase-locking, not a knob.** (Kraken/Kuramoto) Timing feel emerges from coupled oscillators, computed for real. d120 rolls seed each note's micro-variance (detune cents, velocity, filter wobble, pan drift); the groove field pulls the ensemble together. `humanize seed N` makes it deterministic.
6. **d120 uniqueness at birth.** (N8toriousAi's law) Every note-agent rolls d120 on spawn. The roll is visible in the note's inspector and drives its micro-character. No two renders are identical unless seeded — and seeding is one word.
7. **Live eval swaps conductors, never stops the band.** (Impromptu + Tidal) Re-evaluating a `loop` block hot-swaps its pattern at the next cycle boundary. Sounding notes are untouched — they finish their lifecycles. The REPL is Alda's "Play Loop" grown up.
8. **Text is primary; everything else is a compiled view.** (LilyPond's lesson) The code is the artifact. Audio, the patch diagram, a piano-roll, even notation later — all backends over one source.

## Concrete sketch: 4-bar loop — bassline, pad, drums

```
tempo 120

voice bass: saw wave through lowpass 700, punchy, short notes
voice pad:  two triangles detuned, slow attack, long release
voice kit:  drum samples

groove tight            # kuramoto coupling high — the swarm locks
humanize seed 1207      # every note rolls d120 at birth, reproducibly

loop 4 bars:
  bass plays  c2 c2 | g2 g2 | a2 a2 | f2 g2
  pad  holds  [c3 e3 g3] each bar, root follows bass
  kit  plays  kick - snare - | kick - snare - | kick kick snare - | kick - snare crash
```

Reading notes:
- `voice X:` declares a timbre contract (the SynthDef). Words like `saw wave`, `lowpass 700`, `slow attack` map to node-graph builders; anything deeper drops into the DSP combinator register when needed.
- `loop 4 bars:` is the conductor block — independently re-evaluable live.
- Inside, each line is `<voice> <verb> <mini-notation>`. Verbs are articulations and also agent-behavior selectors: `plays` (default ADSR), `holds` (long sustain, slow release), `stabs`, `rolls`, etc.
- Mini-notation (from Tidal, trimmed): `|` bar lines, `-` rest, `*` repeat (`bd*4`), `[]` subdivide a beat, `<>` alternate per cycle, `,` layer polyphonically. Note tokens are Alda-readable: `c2`, `g2`, `f+` for F#.
- `pad holds [c3 e3 g3] each bar, root follows bass` — the pad is one agent per chord per bar (long-lived agents), and `root follows bass` is inter-agent coordination: the pad agent *listens* to the bass agent's root. Agents can subscribe to each other, not just to the groove field. (This is the Kraken tentacle model applied to harmony.)
- Every spawned note rolls d120 at birth: detune ±6 cents, velocity ±8%, filter ±5%, pan drift. The inspector shows each note's roll.

A second, denser example showing the live-coder register:

```
loop 4 bars:
  kit plays  bd*4, [~ <sd cp>]*2, [~ hh]*4      # one-line EDM kit (Tidal-style)
  bass plays <c2 g2 a2 f2>                     # <> = a different root each cycle
```

## Architecture notes

**Pipeline: text → conductor → scheduler → agents → WebAudio.**

1. **Parse.** English surface → AST (small PEG/parser). Mini-notation strings → event lists via a Tidal-style mini-parser. `voice` bodies → DSP graph IR (nodes + edges + params).
2. **Conductor (pattern layer).** Each `loop` block compiles to a *pattern function*: `cycle → [spawn events]`. Pure functions of cycle time (Tidal/Strudel) — composable, stateless, hot-swappable. This is the coordination protocol.
3. **Scheduler.** 25ms JS timer, 120ms lookahead (Strudel's numbers, proven). Converts event cycle-times → `audioCtx.currentTime`; spawns note-agents with sample-accurate `start(t)`. The *only* place wall-clock meets musical time.
4. **Note-agent runtime.** Each agent = JS object `{pitch, t0, dur, voice, roll120, phase, behavior}` + an instantiated WebAudio subgraph from its voice template. Lifecycle state machine: `birth → sustain → release → cleanup` (`onended` → disconnect; zero leaks). Agents never communicate through shared mutable state — only through the groove field and explicit subscriptions (bass root → pad).
5. **Voice/DSP core.** v1: functional node-graph templates in JS — FAUST's five combinators re-expressed (`series`, `parallel`, `split`, `merge`, `feedback`) over WebAudio node builders. v2: real FAUST DSP compiled to WASM → AudioWorklet for heavy voices (convolution, big FM). Voice IR is JSON (nodes/edges) — the same IR a visual patch editor renders.
6. **Groove field (Kuramoto).** Per cycle: collect subscriber phase offsets → compute circular mean → nudge each offset by `K·sin(mean − θᵢ)`. K from `groove tight/loose/off` (0.9 / 0.3 / 0). d120 roll sets initial offset. ~10 lines, real math.
7. **Live-eval loop.** Each `loop` block has an ID; re-eval replaces its pattern function; swap happens at the next cycle boundary; in-flight agents unaffected. (Impromptu proved the performance model; Tidal proved the swap semantics.)
8. **Visual patching ↔ code.** Voice definitions live as graph IR. The patch view renders boxes (nodes) and cords (edges); dragging a cord edits the IR; the code view regenerates the `voice` stanza from the IR. Control-rate vs audio-rate edges are typed (Max's honest split, kept as edge kinds). One truth, two editors.

**What compiles to what (one line each):** English surface → AST → conductor pattern functions; mini-notation → event lists; voice stanzas → WebAudio graph templates (v1) / FAUST→WASM worklets (v2); loop blocks → hot-swappable cycle functions; the whole session → the agent swarm at runtime.

## Hard tradeoffs (named, with positions)

1. **Sample-accurate timing vs. implementation simplicity.** WebAudio gives sample-accurate *execution* (`start(t)`), but JS timers can't *schedule* sample-accurately. Position: lookahead scheduler (25ms tick / 120ms horizon) like Strudel and SuperCollider — timer granularity at the decision layer, sample accuracy at the audio layer. Never pretend the JS thread is the audio thread.
2. **Spawn-per-note vs. voice pooling.** The honest agent model spawns a subgraph per note — simple lifecycles, real GC churn. Position: spawn-per-note with a ~64-concurrent-note cap for v1 (a dense 4-bar loop rarely exceeds 24); pool nodes only if profiling demands it. Correctness of the lifecycle model beats early optimization.
3. **Notation vs. patterns.** Alda-linear vs Tidal-cyclical is a false war — they're two syntaxes over one event stream. Position: support both; `plays` lines accept either bare note runs or mini-notation. Don't make the user pick a tribe.
4. **English verbosity vs. live-coding speed.** Plain sentences are slow to type under stage lights. Position: two registers — English stanzas for structure, mini-notation strings for density, and (later) snippet expansion. Readability is the default; terseness is always one string away.
5. **Determinism vs. humanization.** d120 rolls make every render unique, which fights reproducibility. Position: `humanize seed N` pins everything; default is seeded per session and the seed is displayed. A render is reproducible iff you keep the seed.
6. **WebAudio ceiling.** Graph-land can't do heavy convolution or massive FM stacks at 60+ voices. Position: v1 stays in WebAudio graphs; the FAUST→WASM→AudioWorklet path is designed in from day one (voice IR already abstracts the backend), not bolted on later.
7. **Browser autoplay policy.** AudioContext needs a user gesture. Position: don't fight it — the REPL's first keypress *is* the downbeat. "Press any key to start the band" is a feature: it makes the first cycle land exactly when the performer is ready.
8. **Agent purity vs. pragmatism.** True per-note agents with zero shared state is clean but harmonically dumb (no voice-leading, no shared LFO). Position: agents coordinate through *subscriptions* (pad follows bass root) and the *groove field* — narrow, explicit channels, never shared mutable soup. Kraken's rule: contracts, not dependencies.

---

# Build order (opinionated)
1. Mini-notation parser + scheduler + one saw voice + note-agent lifecycle (a beep that lives and dies correctly is the whole thesis in miniature).
2. English surface for `tempo`/`voice`/`loop`/`plays`/`holds` + Alda-style note tokens.
3. d120 birth rolls + inspector showing them.
4. Groove field (Kuramoto) + `groove` stanza.
5. Live-eval loop with cycle-boundary swaps.
6. Drum samples + kit voice.
7. Patch view round-tripping on voice IR.
8. FAUST→WASM voice backend.
