# Unified Music Code — Roadmap

**Goal:** One language for music where notes are micro-agents and patterns conduct — browser-native, live-coding at its heart, distilled from 12 systems (ChucK, Csound, FAUST, Impromptu, SuperCollider, TidalCycles, Alda, LC, LilyPond, Max/MSP, Pure Data, Strudel).
**Starting point:** Synthesis at `unified-synthesis.md` (study complete 2026-10-17). No code yet. **Name TBD by N8toriousAi** (d120 naming when he calls it).

## Phase 1: The thesis in miniature (DONE 2026-10-17)

**Target:** A single HTML file. English surface + mini-notation, WebAudio scheduler, note-agents with real birth→sustain→release→death, synth voices, d120 rolls, groove field, live eval, agent inspector. The 4-bar demo plays.

- [x] Mini-notation parser: `|` bars, `-` rest, `x` hit, Alda note tokens (`c2`, `f+3`), `[a b]` chords, `tok*n` repeats, `<a b>` per-cycle alternate
- [x] English surface: `tempo`, `voice name: ...`, `groove tight|loose|off`, `humanize seed N`, `loop N bars:` with `plays|holds|stabs`
- [x] Voice descriptors: wave (saw/square/triangle/sine), detuned doubles, lowpass/highpass/bandpass, envelope words (punchy, slow attack, long release, pluck), synth drums (kick/snare/hat/crash)
- [x] Scheduler: 25ms timer, 120ms lookahead, sample-accurate `start(t)` — the only place wall-clock meets musical time
- [x] Note-agent runtime: own WebAudio subgraph per note, d120 roll at birth (detune ±6¢, velocity ±8%, filter ±5%, pan drift), `onended` cleanup, no shared mutable state
- [x] Groove field: per-cycle Kuramoto relaxation toward the circular mean (K = 0.9/0.3/0)
- [x] Live eval: Ctrl+Enter hot-swaps loop patterns at the next cycle boundary; in-flight agents untouched
- [x] Inspector: live agent list (voice, pitch, d120 roll, lifecycle state), cycle readout, parse errors in plain language
- [x] Default demo: the 4-bar sketch from the synthesis

**Exit criteria (all passed headless 2026-10-17):** zero JS errors on load; demo parses to 47 events/cycle; play → 36 live agents, `audioCtx.state === 'running'`; live swap mid-play → band never stops; stop → 0 agents (clean release); same seed → same first roll (d11).

## Phase 2: Determinism + drum samples (NOT STARTED)

**Target:** `humanize seed N` pins every roll (session seed displayed); kit voice loads real samples (URL/local), synth drums stay as fallback.

**Exit criteria:** Two runs with the same seed produce identical roll sequences; sample kit plays without network errors when files exist.

## Phase 3: Patch view round-trip (NOT STARTED)

**Target:** Voice IR (JSON graph) renders as a visual patch — boxes and cords edit the same IR the code compiles from. Control-rate vs audio-rate edges typed (Max's honest split, kept as edge kinds).

**Exit criteria:** Edit a filter cutoff in the patch view → code regenerates with the new value; edit code → patch redraws.

## Phase 4: FAUST→WASM voice backend (NOT STARTED)

**Target:** Voice bodies compile through FAUST's five combinators to WASM → AudioWorklet for heavy DSP. Designed in from day one via the voice IR abstraction.

**Exit criteria:** A FAUST-defined voice plays through the same note-agent lifecycle as graph voices.

## Phase 5: Notation as a compiled view (NOT STARTED)

**Target:** LilyPond's lesson inverted — the text is primary; engraved notation renders as one more backend over the same source.

**Exit criteria:** A loop renders as readable staff notation.

## Design Principles (all phases — from the synthesis)

1. **Notes are agents; patterns conduct.** (ChucK shreds + SuperCollider Synths + Kraken) Notes live their own lifecycle untouched while sounding. No note manager.
2. **English on the surface, density in the strings.** (Alda + Tidal) `bass plays …` reads plain; rhythm detail lives in mini-notation strings.
3. **Conduct in cycles, execute in samples.** (Tidal + ChucK + WebAudio) Bars for humans; sample-accurate starts for machines. One clock domain at the edge, bridged by the lookahead scheduler.
4. **Voices are contracts; timbres are patches.** (SuperCollider + FAUST + Max/PD) A voice is a named signal-graph template; notes are instances. Same IR renders as patch.
5. **Groove is phase-locking, not a knob.** (Kraken/Kuramoto) `groove tight/loose/off` = coupling K 0.9/0.3/0. Real math.
6. **d120 uniqueness at birth.** Every note-agent rolls d120 on spawn; visible in the inspector. `humanize seed N` pins it.
7. **Live eval swaps conductors, never stops the band.** (Impromptu + Tidal) Re-evaluate swaps at the cycle boundary; in-flight agents unaffected.
8. **Text is primary; everything else is a compiled view.** (LilyPond, inverted)

## What got built today (2026-10-17)

- Study of all 12 systems complete → `unified-synthesis.md` (steal/leave per system, 8 principles, 4-bar sketch, architecture, tradeoffs, build order)
- N8toriousAi's law folded in: notes are micro-agents (birth/sustain/release), patterns are the coordination protocol
- ROADMAP.md written — roadmap before code, per the standing law
- Phase 1 BUILT + VERIFIED: `music-code.html` (119KB single file, Caveat embedded) — 47 events/cycle, 36 live agents at play, clean release to 0, live eval swap without stopping, zero JS errors
