Sync from GitHub 6feaf31d

.gitignore

@@ -0,0 +1,96 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build outputs
+.next/
+out/
+dist/
+build/
+*.tsbuildinfo
+
+# Logs
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+*.log
+
+# Environment
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Test coverage
+coverage/
+.nyc_output/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Audio service
+services/audio/models/
+services/audio/loras/
+services/audio/cache/
+services/audio/__pycache__/
+
+# Training data (large, keep manifest only)
+data/training/*.wav
+data/training/*.mp3
+data/training/*.flac
+
+# openlore
+.openlore/
+.openlore/analysis/
+.openlore/serve.log
+.openlore/serve.pid
+
+# OS
+Thumbs.db
+
+# text2midi (cloned model repo, not part of this project)
+text2midi/
+
+# Scratch + source song data (user's GP files, not in git per conftest)
+# Source song folders / individual song files
+gp5_songs/
+*.gp
+*.gp5
+
+# Conversion-corpus fixtures (GP files stay out of git; only baseline.yaml is tracked)
+tests/fixtures/
+
+# Event-trace scratch dumps
+fallen_events.json
+summoning_js_events.json
+
+# Generated keyswitched MIDI output (regenerable via gp5_to_keyswitched_mid.py)
+# Per-track output lands in song-named dirs at repo root (e.g. "Altars rev Yes Breakdown/")
+Altars rev Yes Breakdown/
+Sacrifice ReDrum Full v2 gracenotes/
+The Summoning Aug 2026/
+*.keyswitched.mid
+
+# Jam Buddy generated WAVs (regenerable via the webapp / tools/jam_buddy.py)
+generations/
+
+# SA3 engine — large venv + license-gated weights; regenerable, keep out of git
+stable-audio-3/
+toggle-switch.webp

Dockerfile

@@ -0,0 +1,48 @@
+# Jam Buddy — HF Space (Docker)
+#
+# Builds the Next.js webapp + a lightweight Python env for the SA3 API adapter.
+# The Space runs in API mode only (no local torch/SA3 — generation goes to the
+# Stability REST API via STABILITY_API_KEY). The route resolves the Python
+# interpreter from JAM_BUDDY_PYTHON, which we set to the container python.
+
+# ---- Build stage: Next.js ----
+FROM node:20-slim AS web-build
+WORKDIR /app
+# pnpm workspace: copy manifests first for layer caching
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY apps/web/package.json apps/web/package.json
+COPY packages/ packages/
+RUN corepack enable && pnpm install --frozen-lockfile
+# Copy source + build
+COPY apps/web apps/web
+COPY tsconfig.base.json .
+RUN cd apps/web && pnpm build
+
+# ---- Runtime stage ----
+FROM node:20-slim
+WORKDIR /app
+
+# Python for the SA3 API adapter (lightweight: no torch).
+RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip \
+    && rm -rf /var/lib/apt/lists/*
+ENV JAM_BUDDY_PYTHON=/usr/bin/python3
+
+# Copy the built web app + the tools the API route shells to.
+COPY --from=web-build /app/apps/web/.next apps/web/.next
+COPY --from=web-build /app/apps/web/package.json apps/web/package.json
+COPY --from=web-build /app/apps/web/node_modules apps/web/node_modules
+COPY --from=web-build /app/node_modules node_modules
+COPY --from=web-build /app/packages packages
+COPY apps/web/next.config.mjs apps/web/next.config.mjs
+COPY apps/web/public apps/web/public 2>/dev/null || true
+COPY tools tools
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+
+# Python deps for tools/jam_buddy_api.py (requests, mido, librosa, scipy, soundfile, numpy).
+RUN python3 -m pip install --no-cache-dir requests mido librosa scipy soundfile numpy
+
+# HF Spaces expects the app on port 7860.
+ENV PORT=7860
+WORKDIR /app/apps/web
+EXPOSE 7860
+CMD ["node", "node_modules/next/dist/bin/next", "start", "-p", "7860"]

MIDI_TO_GP5.md

@@ -0,0 +1,76 @@
+# MIDI → GP5/6 converter — design
+
+## Goal
+Convert a keyswitched MIDI file (one track at a time) back to a Guitar Pro 5/6 file.
+
+## Direction
+Mirror of `gp5_to_keyswitched_mid.py`. Where the forward script uses
+`detect_techniques` to read articulations from `note.effect.*`, the reverse
+script needs to infer articulations from the keyswitch note that
+precedes each pitched note.
+
+## Architecture
+
+```
+midi_to_gp5.py
+├── parse MIDI → flat list of (track_name, channel, notes, keyswitches)
+├── classify tracks (guitar / bass / drums)
+├── for each pitched note, look at the preceding keyswitch note and
+│   in the same tick → infer the technique
+├── build a Song with one Track per MIDI track
+└── write via guitarpro.write()
+```
+
+## Inference rules (keyswitch → technique)
+
+Same dictionary as the forward script, inverted. Driven by `KEYSWITCH_NOTES`
+which maps MIDI note number → technique name:
+
+| Note | Technique | GP5 effect |
+|------|-----------|------------|
+| 17 / 18 | sustain | (no effect — sustain is the default) |
+| 20 | palm_mute | `effect.palmMute = True` |
+| 9 | harmonic | `effect.harmonic = HarmonicEffect(type=Natural)` |
+| 23 | slide_down | `effect.slides = [SlideType.shiftSlideTo]` (with next-note direction) |
+| 24 | slide_up | same |
+| 26 | hammer | `effect.hammer = True` |
+| 27 | slide_in | `effect.grace = GraceEffect(transition=slide)` |
+| 91 | bend | `effect.bend = BendEffect(points=[...])` |
+
+Drum notes use standard GM mappings (MIDI 36 = kick, 38 = snare, 42 = hi-hat closed).
+
+## Open questions
+
+1. **Tie detection**: notes whose `note_on` happens before the previous
+   `note_off` for the same pitch → ties. Inferred from MIDI timing.
+2. **Bend reconstruction**: reading pitch wheel events from MIDI is
+   possible but fragile. Most keyswitch-instrumented MIDIs don't include
+   pitch bend. Initially: skip bend (write straight notes).
+3. **Slide direction (up/down)**: target pitch is the next note on the
+   same channel. We don't know the target string, so we use the pitch
+   comparison and let the bar position fill in.
+4. **String/fret selection**: pick the lowest playable fret on the
+   appropriate string. Not unique; heuristic only.
+5. **Tuning**: read from existing GP5 file or default to standard EADGBE.
+6. **Track routing**: user passes `--track-name "Distortion Guitar"` and
+   `--instrument guitar|bass|drums` to control the new GP track.
+
+## File layout
+
+```
+midi_to_gp5.py    # the converter
+tests/
+  test_midi_to_gp5.py    # round-trip tests
+  expected/
+    *.mid    # input fixtures (committed)
+    *.gp5    # expected outputs (committed)
+```
+
+## Status
+
+- [x] Design above
+- [ ] MIDI parser
+- [ ] Track classifier
+- [ ] Articulation inferer
+- [ ] Song builder
+- [ ] Tests

README.md

@@ -1,10 +1,88 @@
----
-title: Jam Buddy
-emoji: 🌍
-colorFrom: purple
-colorTo: gray
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Jam Buddy
+
+> An AI music companion that listens to what you play and joins in — at your
+> tempo, in the instrument you pick. Built for the Stability AI Challenge at
+> Music Hackspace Montreal (August 22–23, 2026).
+
+## What this is
+
+**Jam Buddy** is a call-and-response music practice partner. You start playing,
+it joins in.
+
+- Load a **MIDI take** (from a controller) — the buddy detects your tempo and
+  matches its length, then responds with a complementary part in your chosen
+  instrument at the same tempo.
+- Load an **audio take** (mic/interface) — the buddy uses Stable Audio 3's
+  audio-to-audio path to actually *hear your groove* and respond to it
+  rhythmically.
+- Pick an **instrument** (bass / lead / rhythm / synth / drums), a **genre**,
+  and a **mood** — the buddy generates the response with SA3.
+- **PLAY BOTH** plays your take and the buddy's response together, in tempo.
+- Every response is saved to `generations/` so you can keep and inspect what it
+  produced.
+
+The whole thing is **screenreader-compatible by design**: every knob is a
+labelled `<input type=range>`, buttons have accessible names, and the status is
+announced via `aria-live`. Voice-first *is* accessibility.
+
+The SA3 generation runs **locally on the open Stable Audio 3 weights** —
+`small-music` for melodic instruments, `small-sfx` for clean isolated drum hits.
+
+Built for the **Stability AI Challenge** at Music Hackspace Montreal
+(August 22–23, 2026, in partnership with MUTEK).
+
+## Quick start (web app)
+
+```bash
+cd apps/web
+pnpm install
+pnpm dev
+# → http://localhost:3000
+```
+
+The web app shells out to `tools/jam_buddy.py` (the SA3 pipeline). That needs
+the `stable-audio-3` venv + a one-time model download. See
+[`docs/06-stable-audio-integration.md`](docs/06-stable-audio-integration.md).
+
+### CLI (the pipeline directly)
+
+```bash
+# MIDI take → tempo + length matched, then respond with bass
+python3 tools/jam_buddy.py --midi take.mid --instrument bass --out out.wav
+
+# Audio take → audio-to-audio, responds to the groove
+python3 tools/jam_buddy.py --wav take.wav --genre metal --instrument lead --out out.wav
+
+# Manual knob only
+python3 tools/jam_buddy.py --bpm 120 --instrument drums --out out.wav
+```
+
+## Documentation
+
+| Doc | Purpose |
+|---|---|
+| [`docs/01-vision.md`](docs/01-vision.md) | What we're building and why |
+| [`docs/02-architecture.md`](docs/02-architecture.md) | System architecture, services, data flow |
+| [`docs/03-data-model.md`](docs/03-data-model.md) | Prompt builder, knobs, generation metadata |
+| [`docs/05-accessibility.md`](docs/05-accessibility.md) | Screenreader/keyboard accessibility strategy |
+| [`docs/06-stable-audio-integration.md`](docs/06-stable-audio-integration.md) | SA3 setup, audio-to-audio, Vega notes, LoRA |
+| [`docs/07-reaper-integration.md`](docs/07-reaper-integration.md) | DAW integration via Reaper |
+| [`docs/08-build-plan.md`](docs/08-build-plan.md) | Hackathon build plan |
+| [`docs/09-risks.md`](docs/09-risks.md) | Ranked risks + mitigations |
+| [`docs/10-team-pitch.md`](docs/10-team-pitch.md) | Team pitch + skills |
+
+## Conventions
+
+- **Language**: TypeScript (frontend), Python 3.10+ (audio pipeline)
+- **Linting**: ESLint + Prettier (TS), ruff + black (Python)
+- **Accessibility**: axe-core in CI, NVDA + VoiceOver tested before each demo
+- **Commits**: Conventional Commits (`feat:`, `fix:`, `docs:`, etc.)
+- **Branches**: `feat/*`, `fix/*`, `docs/*`, `chore/*`
+
+For the agent harness — commands, test contract, and what's deliberately not in
+git — see [`docs/HARNESS.md`](docs/HARNESS.md).
+
+## License
+
+MIT (code). Generated audio stays local / your own material; no third-party
+samples ship in this repo.

apps/web/.eslintrc.json

@@ -0,0 +1,8 @@
+{
+  "extends": ["next/core-web-vitals", "next/typescript"],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/consistent-type-imports": "warn"
+  },
+  "ignorePatterns": ["node_modules/", ".next/", "dist/", "__tests__/"]
+}

apps/web/__tests__/conversation.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Voice conversation FSM tests.
+ *
+ * Pure transition tests — no DOM, no audio. Verify each state transition
+ * produces the expected next state and side-effects.
+ */
+
+import { describe, it, expect } from "vitest";
+import { transition } from "../lib/voice/conversation";
+import type { ParseResult } from "@patterntalk/shared-types";
+
+describe("voice FSM — happy path", () => {
+  it("idle → listening → parsing → generating → ready on a clean prompt", () => {
+    let s = transition("idle", {}, { type: "START_LISTENING" });
+    expect(s.next).toBe("listening");
+    expect(s.sideEffects.map((e) => e.type)).toContain("START_MIC");
+
+    s = transition(s.next, s.context, { type: "TRANSCRIPT_FINAL", transcript: "d-beat at 180" });
+    expect(s.next).toBe("parsing");
+
+    const parseOk: ParseResult = {
+      ok: true,
+      confidence: 0.95,
+      request: {
+        patternId: "d-beat",
+        patternName: "D-Beat",
+        bars: 4,
+        tempoSource: "prompt",
+        tempoDefault: 120,
+        timeSignature: { numerator: 4, denominator: 4 },
+        tempo: 180,
+      },
+    };
+    s = transition(s.next, s.context, { type: "PARSE_OK", result: parseOk });
+    expect(s.next).toBe("generating");
+
+    s = transition(s.next, s.context, {
+      type: "GENERATION_OK",
+      sampleUrl: "http://localhost:8001/cache/abc.wav",
+    });
+    expect(s.next).toBe("ready");
+    expect(s.context.parsed?.patternId).toBe("d-beat");
+    expect(s.context.sampleUrl).toBe("http://localhost:8001/cache/abc.wav");
+  });
+});
+
+describe("voice FSM — low confidence → confirmation", () => {
+  it("parsing → awaiting-confirmation when PARSE_LOW_CONFIDENCE fires", () => {
+    const lowConf: ParseResult = {
+      ok: false,
+      confidence: 0.4,
+      heardAs: "tupatupa",
+      candidates: [
+        {
+          request: {
+            patternId: "skank",
+            patternName: "Skank Beat",
+            bars: 4,
+            tempoSource: "default",
+            tempoDefault: 120,
+            timeSignature: { numerator: 4, denominator: 4 },
+          },
+          confidence: 0.4,
+          reason: "phonetic match",
+        },
+      ],
+    };
+    const s = transition("parsing", {}, { type: "PARSE_LOW_CONFIDENCE", result: lowConf });
+    expect(s.next).toBe("awaiting-confirmation");
+    const speak = s.sideEffects.find((e) => e.type === "SPEAK");
+    expect(speak).toBeDefined();
+    if (speak && speak.type === "SPEAK") {
+      expect(speak.text).toContain("Skank Beat");
+    }
+  });
+});
+
+describe("voice FSM — error states", () => {
+  it("any state → error on ERROR event", () => {
+    const s = transition("listening", {}, {
+      type: "ERROR",
+      kind: "mic-denied",
+      message: "Microphone access denied. Enable it in browser settings.",
+    });
+    expect(s.next).toBe("error");
+    expect(s.context.error?.kind).toBe("mic-denied");
+  });
+
+  it("GENERATION_FAIL routes to error state", () => {
+    const s = transition("generating", {}, {
+      type: "GENERATION_FAIL",
+      message: "Sample generation timed out. MIDI is still ready.",
+    });
+    expect(s.next).toBe("error");
+    expect(s.context.error?.message).toContain("timed out");
+  });
+});
+
+describe("voice FSM — RESET", () => {
+  it("RESET from any state returns to idle", () => {
+    const s1 = transition("ready", { parsed: { patternId: "x", bars: 4, tempoSource: "default", tempoDefault: 120, timeSignature: { numerator: 4, denominator: 4 } } }, { type: "RESET" });
+    expect(s1.next).toBe("idle");
+    expect(s1.context).toEqual({});
+  });
+});
+
+describe("voice FSM — ignores stray events", () => {
+  it("TRANSCRIPT_FINAL while idle is ignored", () => {
+    const s = transition("idle", {}, { type: "TRANSCRIPT_FINAL", transcript: "hi" });
+    expect(s.next).toBe("idle");
+    expect(s.sideEffects).toHaveLength(0);
+  });
+
+  it("PLAY_START while idle is ignored", () => {
+    const s = transition("idle", {}, { type: "PLAY_START" });
+    expect(s.next).toBe("idle");
+  });
+});

apps/web/__tests__/engine.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Pattern engine tests.
+ *
+ * These are the foundation's correctness contract. They run on every PR.
+ * If they break, the demo breaks — fix the engine, not the test.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  expandPattern,
+  bpmToMicrosecondsPerQuarter,
+  ticksPerBar,
+  TICKS_PER_QUARTER,
+} from "../lib/patterns/engine";
+import dbeat from "../data/patterns/d-beat.json";
+import skank from "../data/patterns/skank.json";
+import type { PatternTemplate } from "@patterntalk/shared-types";
+
+const DB = dbeat as PatternTemplate;
+const SK = skank as PatternTemplate;
+
+describe("engine math primitives", () => {
+  it("computes ticks-per-bar correctly for 4/4", () => {
+    expect(ticksPerBar({ numerator: 4, denominator: 4 })).toBe(1920);
+  });
+
+  it("converts BPM to microseconds-per-quarter-note", () => {
+    expect(bpmToMicrosecondsPerQuarter(120)).toBe(500000);
+    expect(bpmToMicrosecondsPerQuarter(180)).toBe(333333);
+    expect(bpmToMicrosecondsPerQuarter(60)).toBe(1000000);
+  });
+});
+
+describe("expandPattern — d-beat", () => {
+  const events = expandPattern({ template: DB, bars: 1, bpm: 180 });
+
+  it("preserves the template's hit count for 1 bar", () => {
+    expect(events).toHaveLength(DB.hits.length);
+  });
+
+  it("produces 4x hits for 4 bars", () => {
+    const fourBars = expandPattern({ template: DB, bars: 4, bpm: 180 });
+    expect(fourBars).toHaveLength(DB.hits.length * 4);
+  });
+
+  it("starts at tick 0 and respects the 1920 ticks-per-bar window", () => {
+    const tickValues = events.map((e) => e.tick);
+    expect(tickValues[0]).toBe(0);
+    expect(Math.max(...tickValues)).toBeLessThan(1920);
+  });
+
+  it("sorts events by tick ascending", () => {
+    const sorted = [...events].sort((a, b) => a.tick - b.tick);
+    expect(events.map((e) => e.tick)).toEqual(sorted.map((e) => e.tick));
+  });
+
+  it("keeps all velocities in 1–127 range (humanize clamp)", () => {
+    for (const ev of events) {
+      expect(ev.velocity).toBeGreaterThanOrEqual(1);
+      expect(ev.velocity).toBeLessThanOrEqual(127);
+    }
+  });
+
+  it("emits a mix of kick, snare, and ride-bell hits", () => {
+    const limbs = new Set(events.map((e) => e.limb));
+    expect(limbs.has("kick")).toBe(true);
+    expect(limbs.has("snare")).toBe(true);
+    expect(limbs.has("ride-bell")).toBe(true);
+  });
+});
+
+describe("expandPattern — cymbal override", () => {
+  it("replaces ride-bell hits with crash when cymbal override is { type: 'crash' }", () => {
+    const events = expandPattern({
+      template: DB,
+      bars: 1,
+      bpm: 180,
+      overrides: { cymbal: { type: "crash", pattern: "8ths" } },
+    });
+    const rideBellCount = events.filter((e) => e.limb === "ride-bell").length;
+    const crashCount = events.filter((e) => e.limb === "crash").length;
+    expect(rideBellCount).toBe(0);
+    expect(crashCount).toBeGreaterThan(0);
+  });
+
+  it("replaces hihat with hihat-open", () => {
+    const events = expandPattern({
+      template: SK,
+      bars: 1,
+      bpm: 120,
+      overrides: { cymbal: { type: "hihat-open", pattern: "upstrokes" } },
+    });
+    expect(events.filter((e) => e.limb === "hihat-open").length).toBeGreaterThan(0);
+    expect(events.filter((e) => e.limb === "hihat").length).toBe(0);
+  });
+});
+
+describe("expandPattern — accents", () => {
+  it("boosts velocity by +20 on beat 1", () => {
+    const baseline = expandPattern({ template: DB, bars: 4, bpm: 180 });
+    const accented = expandPattern({
+      template: DB,
+      bars: 4,
+      bpm: 180,
+      overrides: { accents: ["1"] },
+    });
+
+    // The first kick in each bar is at tick = barIndex * 1920.
+    // Its velocity in DB.hits is 110; humanize can shift ±2.
+    // With accents, raw velocity = 110 + 20 + humanize (range 128–132),
+    // clamped to 127. So expected >= 127.
+    const firstKickPerBar = [0, 1920, 3840, 5760].map(
+      (tick) => accented.find((e) => e.tick === tick && e.limb === "kick")!,
+    );
+    for (const ev of firstKickPerBar) {
+      expect(ev.velocity).toBeGreaterThanOrEqual(127);
+      // Clamped to 127
+      expect(ev.velocity).toBeLessThanOrEqual(127);
+    }
+    // Sanity: without accents, same hit should be lower.
+    const firstUnaccented = baseline
+      .filter((e) => e.limb === "kick" && [0, 1920, 3840, 5760].includes(e.tick))
+      .map((e) => e.velocity);
+    expect(firstUnaccented.every((v) => v < 127)).toBe(true);
+  });
+
+  it("regression: accents apply to ALL bars, not just bar 0", () => {
+    // Catches the bug where barTicks was being miscomputed from
+    // bars[1]?.tick (which is undefined for ExpandedBar), making
+    // accents only match for bar 0.
+    const accented = expandPattern({
+      template: DB,
+      bars: 4,
+      bpm: 180,
+      overrides: { accents: ["1"] },
+    });
+    const beatOneKicks = [0, 1920, 3840, 5760]
+      .map((tick) => accented.find((e) => e.tick === tick && e.limb === "kick"))
+      .filter((e): e is NonNullable<typeof e> => e !== undefined);
+    expect(beatOneKicks).toHaveLength(4);
+    for (const ev of beatOneKicks) {
+      expect(ev.velocity).toBe(127); // 110 + humanize(±2) + 20 → clamped
+    }
+  });
+});
+
+describe("expandPattern — integration sanity", () => {
+  it("d-beat at 180 BPM for 4 bars produces a tick range equal to 4 × ticksPerBar", () => {
+    const events = expandPattern({ template: DB, bars: 4, bpm: 180 });
+    const maxTick = Math.max(...events.map((e) => e.tick));
+    expect(maxTick).toBeLessThan(4 * ticksPerBar({ numerator: 4, denominator: 4 }));
+  });
+
+  it("skank at 120 BPM has 8 hits in 1 bar", () => {
+    const events = expandPattern({ template: SK, bars: 1, bpm: 120 });
+    expect(events).toHaveLength(SK.hits.length);
+    // 2 kicks + 2 snares + 4 hihats
+    expect(events.filter((e) => e.limb === "kick")).toHaveLength(2);
+    expect(events.filter((e) => e.limb === "snare")).toHaveLength(2);
+    expect(events.filter((e) => e.limb === "hihat")).toHaveLength(4);
+  });
+
+  it("respects TICKS_PER_QUARTER constant", () => {
+    expect(TICKS_PER_QUARTER).toBe(480);
+  });
+});

apps/web/__tests__/player.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { midiToFreq, parseMidi, isPercussion, type ParsedNote } from "@/lib/jambuddy/player";
+
+describe("midiToFreq", () => {
+  it("maps A4 (69) to 440 Hz", () => {
+    expect(midiToFreq(69)).toBeCloseTo(440, 3);
+  });
+  it("maps C4 (60) to ~261.6 Hz", () => {
+    expect(midiToFreq(60)).toBeCloseTo(261.63, 1);
+  });
+  it("is an octave up 12 semitones", () => {
+    expect(midiToFreq(81)).toBeCloseTo(midiToFreq(69) * 2, 3);
+  });
+});
+
+describe("parseMidi", () => {
+  it("throws a readable error for non-MIDI bytes", () => {
+    expect(() => parseMidi(new Uint8Array([1, 2, 3]).buffer)).toThrow();
+  });
+});
+
+describe("isPercussion", () => {
+  it("flags GM channel 9 as percussion", () => {
+    const drum: ParsedNote = {
+      time: 0,
+      midi: 36,
+      duration: 0.1,
+      velocity: 0.9,
+      channel: 9,
+    };
+    expect(isPercussion(drum)).toBe(true);
+  });
+  it("does not flag a normal channel", () => {
+    const bass: ParsedNote = {
+      time: 0,
+      midi: 40,
+      duration: 0.2,
+      velocity: 0.8,
+      channel: 0,
+    };
+    expect(isPercussion(bass)).toBe(false);
+  });
+});

apps/web/__tests__/prompt.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildPrompt,
+  type BuddyKnobs,
+} from "@/lib/jambuddy/prompt";
+
+const base: BuddyKnobs = {
+  instrument: "bass",
+  inputInstrument: "drums",
+  genre: "metal",
+  mood: "energetic",
+  bpm: 184,
+};
+
+describe("buildPrompt", () => {
+  it("follows the AudioSparx tag structure: TrackType, Genre, Moods, Instruments, BPM, studio", () => {
+    const { prompt } = buildPrompt(base);
+    expect(prompt).toContain("TrackType: Music, VocalType: Instrumental");
+    expect(prompt).toContain("Genre: Heavy Metal");
+    expect(prompt).toContain("Moods: Energetic");
+    expect(prompt).toContain("Instruments: Bass Guitar");
+    expect(prompt).toContain("184 BPM");
+    expect(prompt).toContain("studio recording");
+  });
+
+  it("omits the genre fragment when genre is 'any'", () => {
+    const { prompt } = buildPrompt({ ...base, genre: "any" });
+    expect(prompt).not.toContain("Genre:");
+    expect(prompt).toContain("TrackType: Music, VocalType: Instrumental");
+    expect(prompt).toContain("184 BPM");
+  });
+
+  it("clamps BPM to a sane range", () => {
+    const low = buildPrompt({ ...base, bpm: 5 });
+    expect(low.prompt).toContain("40 BPM");
+    const high = buildPrompt({ ...base, bpm: 9999 });
+    expect(high.prompt).toContain("240 BPM");
+  });
+
+  it("sets a negative prompt that steers away from a full mix", () => {
+    const { negativePrompt } = buildPrompt(base);
+    expect(negativePrompt).toContain("field recording");
+    expect(negativePrompt).toContain("full band");
+    expect(negativePrompt).toContain("vocals");
+  });
+
+  it("rounds fractional BPM", () => {
+    const { prompt } = buildPrompt({ ...base, bpm: 184.6 });
+    expect(prompt).toContain("185 BPM");
+  });
+
+  it("negates the user's input instrument in the negative prompt when it differs from the buddy", () => {
+    const { negativePrompt } = buildPrompt({ ...base, inputInstrument: "drums" });
+    expect(negativePrompt).toContain("drums");
+  });
+
+  it("does not negate the buddy's own instrument family in the negative prompt (lead guitar + input guitar)", () => {
+    const { negativePrompt } = buildPrompt({
+      ...base,
+      instrument: "lead",
+      inputInstrument: "guitar",
+    });
+    // buddy=lead is in the guitar family; adding "guitar" to the negative
+    // would steer SA3 away from the buddy itself, so we must NOT add it.
+    expect(negativePrompt).not.toContain("guitar");
+  });
+
+  it("drops 'percussion' from the negative when the buddy is drums", () => {
+    const { negativePrompt } = buildPrompt({
+      ...base,
+      instrument: "drums",
+      inputInstrument: "other",
+    });
+    expect(negativePrompt).not.toContain("percussion");
+  });
+
+  it("omits the complement clause when inputInstrument is 'other'", () => {
+    const { prompt } = buildPrompt({ ...base, inputInstrument: "other" });
+    expect(prompt).not.toContain("complement");
+  });
+});

apps/web/app/api/jambuddy/detect/route.ts

@@ -0,0 +1,98 @@
+import { NextRequest, NextResponse } from "next/server";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { BuddyGenre } from "@/lib/jambuddy/prompt";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Jam Buddy BPM/duration detection.
+ *
+ * POST /api/jambuddy/detect
+ *   body: { midi?: string(base64), audio?: string(base64), genre?: BuddyGenre }
+ *
+ * Shells to tools/jam_buddy_api.py (or jam_buddy.py) with --detect-only and
+ * returns the detected BPM + duration so the client can PRE-FILL the tempo
+ * knob. The knob stays authoritative afterward.
+ */
+export async function POST(req: NextRequest) {
+  let body: { midi?: string; audio?: string; genre?: BuddyGenre };
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "invalid JSON body" }, { status: 400 });
+  }
+  if (!body.midi && !body.audio) {
+    return NextResponse.json(
+      { error: "need a midi or audio take to detect tempo from" },
+      { status: 400 },
+    );
+  }
+
+  // Resolve repo root + python like the main route.
+  const exists = (p: string) => require("node:fs").existsSync(p);
+  let repoRoot: string | null = process.env.JAM_BUDDY_ROOT ?? null;
+  if (!repoRoot) {
+    let cur = process.cwd();
+    while (cur && !exists(join(cur, "tools", "jam_buddy_api.py"))) {
+      const parent = join(cur, "..");
+      if (parent === cur) break;
+      cur = parent;
+    }
+    repoRoot = exists(join(cur, "tools", "jam_buddy_api.py")) ? cur : null;
+  }
+  if (!repoRoot) {
+    return NextResponse.json(
+      { error: "could not locate repo root" },
+      { status: 500 },
+    );
+  }
+  const python =
+    process.env.JAM_BUDDY_PYTHON ??
+    (exists(join(repoRoot, "stable-audio-3", ".venv", "Scripts", "python.exe"))
+      ? join(repoRoot, "stable-audio-3", ".venv", "Scripts", "python.exe")
+      : "python3");
+  const script = join(repoRoot, "tools", "jam_buddy_api.py");
+
+  try {
+    const args = ["--detect-only"];
+    if (body.midi) {
+      const midiPath = join(tmpdir(), `jambuddy-detect-${Date.now()}.mid`);
+      await writeFile(midiPath, Buffer.from(body.midi, "base64"));
+      args.push("--midi", midiPath);
+    } else if (body.audio) {
+      const audioPath = join(tmpdir(), `jambuddy-detect-${Date.now()}.wav`);
+      await writeFile(audioPath, Buffer.from(body.audio, "base64"));
+      args.push("--wav", audioPath);
+      // Genre prior for audio detection (helps octave disambiguation).
+      if (body.genre) args.push("--genre", body.genre);
+    }
+    const { stdout } = await execFileAsync(python, [script, ...args], {
+      timeout: 60_000,
+      maxBuffer: 2 * 1024 * 1024,
+    });
+    // stdout ends with "DETECT <bpm> <duration>"
+    const m = stdout.match(/DETECT\s+([\d.]+)\s+([\d.]+)/);
+    const bpmVal = m?.[1];
+    const durVal = m?.[2];
+    if (!bpmVal || !durVal) {
+      return NextResponse.json(
+        { error: "detection produced no result", detail: stdout.trim() },
+        { status: 500 },
+      );
+    }
+    return NextResponse.json({
+      bpm: Math.round(parseFloat(bpmVal)),
+      duration: parseFloat(durVal),
+    });
+  } catch (err) {
+    const detail =
+      err instanceof Error
+        ? (err as Error & { stderr?: string }).stderr?.trim() || err.message
+        : String(err);
+    return NextResponse.json({ error: "detection failed", detail }, { status: 500 });
+  }
+}

apps/web/app/api/jambuddy/route.ts

@@ -0,0 +1,248 @@
+import { NextRequest, NextResponse } from "next/server";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { writeFile, mkdir, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildPrompt, MODEL_FOR_INSTRUMENT, type BuddyKnobs } from "@/lib/jambuddy/prompt";
+
+const execFileAsync = promisify(execFile);
+
+interface JambuddyBody {
+  knobs?: BuddyKnobs;
+  /** Override BPM. If a MIDI take is given, detection runs on it instead. */
+  bpm?: number;
+  /** Base64-encoded MIDI take (a controller recording). */
+  midi?: string;
+  /** Base64-encoded audio take (mic/interface/render) for audio-to-audio. */
+  audio?: string;
+  /** Response length in seconds. Default 30 (ignored when a take is provided). */
+  duration?: number;
+  /** Generation backend: "local" (CPU SA3) or "api" (Stable Audio 3.0 Large, 26 credits/gen). */
+  mode?: "local" | "api";
+}
+
+/**
+ * Jam Buddy API route.
+ *
+ * POST /api/jambuddy
+ *   body: { knobs, bpm?, midi?, duration? }
+ *
+ * Shells to tools/jam_buddy.py (the SA3 pipeline) and returns the generated
+ * WAV as audio/wav. The Python side does the heavy lifting (SA3 generation +
+ * MIDI tempo detection); this route just wires the webapp to it.
+ *
+ * If a MIDI take is uploaded, the buddy detects the tempo from it (so it
+ * "joins in" at YOUR tempo) and the manual `bpm` knob is ignored.
+ *
+ * The SA3 venv python is resolved from env (JAM_BUDDY_PYTHON) or defaults to
+ * the stable-audio-3 venv. The script path is resolved from the repo root.
+ */
+export async function POST(req: NextRequest) {
+  let body: JambuddyBody;
+  try {
+    body = await req.json();
+  } catch {
+    return NextResponse.json({ error: "invalid JSON body" }, { status: 400 });
+  }
+
+  if (!body.knobs) {
+    return NextResponse.json({ error: "missing knobs" }, { status: 400 });
+  }
+
+  const { prompt, negativePrompt } = buildPrompt(body.knobs);
+  const bpm = body.bpm ?? 120;
+  // Drums use small-sfx (clean isolated hits); everything else small-music.
+  const model = MODEL_FOR_INSTRUMENT[body.knobs.instrument];
+
+  // Resolve the Python interpreter + script by locating the repo root, which
+  // contains tools/jam_buddy.py. Walk up from the Next server cwd until we
+  // find it — the cwd differs between `pnpm dev` (apps/web) and a root-level
+  // launch, so don't assume a fixed number of levels up. Allow an env override.
+  const exists = (p: string) => require("node:fs").existsSync(p);
+  let repoRoot: string | null = process.env.JAM_BUDDY_ROOT ?? null;
+  if (!repoRoot) {
+    let cur = process.cwd();
+    while (cur && !exists(join(cur, "tools", "jam_buddy.py"))) {
+      const parent = join(cur, "..");
+      if (parent === cur) break;
+      cur = parent;
+    }
+    repoRoot = exists(join(cur, "tools", "jam_buddy.py")) ? cur : null;
+  }
+  if (!repoRoot) {
+    return NextResponse.json(
+      { error: "could not locate repo root (tools/jam_buddy.py)" },
+      { status: 500 },
+    );
+  }
+  // Thread the TS-built AudioSparx prompt through so Genre:/Moods:/Instruments
+  // tags actually reach SA3. The Python CLI also accepts --instrument/--genre
+  // for standalone use, but route.ts is authoritative here.
+  // Resolve the Python interpreter. Prefer JAM_BUDDY_PYTHON (set in the HF
+  // Space container to /usr/bin/python3); fall back to the local SA3 venv;
+  // finally to `python3` on PATH (container / CI). The venv path is Windows
+  // and won't exist in the Linux Space, so the fallback matters.
+  const venvPython = join(repoRoot, "stable-audio-3", ".venv", "Scripts", "python.exe");
+  const python =
+    process.env.JAM_BUDDY_PYTHON ??
+    (exists(venvPython) ? venvPython : "python3");
+
+  // Local = Stable Audio small models on CPU (supports negative prompt, free,
+  // slow). API = Stable Audio 3.0 Large via Stability REST (no negative prompt,
+  // fast, 26 credits/gen). Default to API — key is present, it's faster and
+  // isolates better; the user can flip to local (offline / free) in the GUI.
+  const mode: "local" | "api" =
+    body.mode === "local" ? "local" : "api";
+  const script = join(
+    repoRoot,
+    "tools",
+    mode === "api" ? "jam_buddy_api.py" : "jam_buddy.py",
+  );
+
+  // Always write to a PERSISTENT generations dir at the repo root so the
+  // output survives and is inspectable. Filenames are timestamped + tagged so
+  // you can tell them apart. The dir is gitignored (regenerable artifact).
+  const generationsDir = join(repoRoot, "generations");
+  await mkdir(generationsDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+  const sourceTag = body.midi ? "midi" : body.audio ? "audio" : "manual";
+  // API returns MP3 (output_format mp3); local returns WAV.
+  const ext = mode === "api" ? "mp3" : "wav";
+  // Descriptive filename: the knob values + input type + engine, sanitized so
+  // you can tell generations apart without opening them.
+  const slug = (s: string) =>
+    s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  const knobBpmSlug = slug(String(body.knobs.bpm));
+  const outName =
+    [
+      stamp,
+      slug(body.knobs.instrument),
+      slug(body.knobs.genre),
+      slug(body.knobs.mood),
+      body.knobs.inputInstrument && body.knobs.inputInstrument !== "other"
+        ? `over-${slug(body.knobs.inputInstrument)}`
+        : null,
+      knobBpmSlug ? `${knobBpmSlug}bpm` : null,
+      sourceTag,
+      mode,
+    ]
+      .filter(Boolean)
+      .join("-") + `.${ext}`;
+  const outPath = join(generationsDir, outName);
+
+  try {
+    // Build args. Option A: the knob BPM is authoritative and ALWAYS sent. The
+    // take (if any) sets duration + drives audio-to-audio; it never overrides
+    // the tempo. Detection only pre-fills the knob on the client.
+    const knobBpm = Math.round(
+      Math.max(40, Math.min(240, body.knobs.bpm)),
+    );
+
+    const args = [
+      "--bpm",
+      String(knobBpm),
+      "--instrument",
+      body.knobs.instrument,
+      "--prompt",
+      prompt,
+      "--out",
+      outPath,
+    ];
+    // Local model + negative prompt are CPU-only concepts. The API fixes the
+    // model (stable-audio-3) and accepts NO negative prompt.
+    if (mode === "local") {
+      args.unshift("--model", model);
+      args.push("--negative-prompt", negativePrompt);
+    }
+    if (body.midi) {
+      // MIDI: the take only provides response DURATION (tempo comes from the
+      // knob). Pass --midi so the adapter reads its length for duration.
+      const midiPath = join(tmpdir(), `jambuddy-take-${Date.now()}.mid`);
+      await writeFile(midiPath, Buffer.from(body.midi, "base64"));
+      args.push("--midi", midiPath);
+      console.log(`[jambuddy] MIDI take: duration from it; tempo = knob ${knobBpm}`);
+    } else if (body.audio) {
+      // Audio: pass to SA3 via init_audio so it responds to the groove. Tempo
+      // is still the knob; the take sets duration + drives audio-to-audio.
+      const audioPath = join(tmpdir(), `jambuddy-take-${Date.now()}.wav`);
+      await writeFile(audioPath, Buffer.from(body.audio, "base64"));
+      args.push("--wav", audioPath);
+      args.push("--genre", body.knobs.genre);
+      console.log(`[jambuddy] audio take: audio-to-audio; tempo = ${knobBpm}`);
+    } else {
+      // No take: 4 bars in 4/4 = 16 beats at the knob tempo.
+      // seconds = beats * (60 / bpm) = 16 * 60 / bpm = 960 / bpm.
+      const bars4 = 960 / knobBpm;
+      args.push("--duration", String(Math.max(1, bars4)));
+      console.log(`[jambuddy] no take: 4 bars = ${bars4.toFixed(2)}s @ ${knobBpm} BPM`);
+    }
+
+    const t0 = Date.now();
+    // The Python child needs STABILITY_API_KEY in its env for API mode. Read it
+    // from the repo-root .env (the child's cwd is apps/web, so it can't find it
+    // itself) and pass it explicitly. Local mode ignores it.
+    let childEnv = process.env;
+    if (mode === "api") {
+      const dotenvPath = join(repoRoot, ".env");
+      let apiKey = process.env.STABILITY_API_KEY ?? null;
+      if (!apiKey) {
+        try {
+          const dotenvText = await readFile(dotenvPath, "utf8");
+          const m = dotenvText.match(/^STABILITY_API_KEY=(.+)$/m);
+          const val = m?.[1];
+          if (val) apiKey = val.trim().replace(/^["']|["']$/g, "");
+        } catch {
+          /* .env missing — the child will error clearly */
+        }
+      }
+      if (!apiKey) {
+        throw new Error(
+          "STABILITY_API_KEY not found in repo .env or process env (required for api mode)",
+        );
+      }
+      childEnv = { ...process.env, STABILITY_API_KEY: apiKey };
+    }
+    const { stdout } = await execFileAsync(python, [script, ...args], {
+      timeout: 300_000, // 5 min — SA3 generation on CPU is slow
+      maxBuffer: 10 * 1024 * 1024,
+      env: childEnv,
+    });
+    const generateMs = Date.now() - t0;
+    console.log("[jambuddy] stdout:", stdout);
+    console.log("[jambuddy] generate time:", generateMs, "ms");
+
+    // The script prints the tempo it used, e.g.
+    //   "Detected BPM (MIDI): 117 from ..."  (with a take)
+    //   "Using explicit BPM: 120"            (manual knob)
+    //   "Wrote ...: 30.0s @ 117 BPM"
+    // Parse the final @ <n> BPM so the GUI can show the tempo the buddy locked
+    // onto. Default to the manual bpm knob.
+    let usedBpm = bpm;
+    const atMatch = stdout.match(/@\s*([\d.]+)\s*BPM/i);
+    if (atMatch && atMatch[1]) usedBpm = Math.round(parseFloat(atMatch[1]));
+    console.log("[jambuddy] used BPM:", usedBpm);
+
+    const wav = await readFile(outPath);
+    // API returns MP3, local returns WAV — serve the right content-type.
+    const contentType = mode === "api" ? "audio/mpeg" : "audio/wav";
+    const filename = mode === "api" ? "buddy_response.mp3" : "buddy_response.wav";
+    return new NextResponse(wav, {
+      headers: {
+        "Content-Type": contentType,
+        "Content-Disposition": `attachment; filename="${filename}"`,
+        "X-Jam-Buddy-BPM": String(usedBpm),
+        "X-Jam-Buddy-Time": String(generateMs),
+      },
+    });
+  } catch (err) {
+    console.error("[jambuddy] error:", err);
+    // Surface the underlying stderr so a broken pipeline is diagnosable from
+    // the browser console, not a blank "generation failed".
+    const detail =
+      err instanceof Error
+        ? (err as Error & { stderr?: string }).stderr?.trim() || err.message
+        : String(err);
+    return NextResponse.json({ error: "generation failed", detail }, { status: 500 });
+  }
+}

apps/web/app/globals.css

@@ -0,0 +1,320 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/*
+ * Jam Buddy hardware-sampler rack.
+ * Self-contained dark panel with a rotary-knob look and trigger pads.
+ * Kept as plain CSS so it doesn't fight the Tailwind theme tokens, and
+ * accessibility is preserved (range inputs, focus rings, aria-live).
+ */
+.jambuddy-rack {
+  background: linear-gradient(180deg, #1c1e2b 0%, #12131b 100%);
+  border: 1px solid #2a2d3d;
+}
+
+.jambuddy-pad {
+  border-radius: 0.5rem;
+  border: 1px solid #2a2d3d;
+  background: #1f2130;
+  color: #7f829c;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.7rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  padding: 0.6rem 0;
+  transition: background 0.15s, color 0.15s, box-shadow 0.15s;
+}
+.jambuddy-pad:hover {
+  background: #2a2d3d;
+}
+.jambuddy-pad--on {
+  background: #f4a261;
+  color: #12131b;
+  box-shadow: 0 0 12px rgba(244, 162, 97, 0.4);
+  font-weight: bold;
+}
+
+/* Rotary knob = a styled <input type=range>. A metallic potentiometer: a
+ * brushed-aluminum body with a knurled edge, a gloss highlight, and a real
+ * pointer line that rotates with the value (read off --knob-pct). */
+.jambuddy-knob {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 3.5rem;
+  height: 3.5rem;
+  border-radius: 9999px;
+  background:
+    radial-gradient(circle at 50% 50%, #dfe3ea 0%, #aeb4c0 34%, #5b6270 68%, #3a3f4a 100%);
+  border: 2px solid #2a2d3d;
+  cursor: pointer;
+  position: relative;
+  box-shadow:
+    inset 0 2px 3px rgba(255, 255, 255, 0.5),
+    inset 0 -4px 8px rgba(0, 0, 0, 0.45),
+    0 3px 6px rgba(0, 0, 0, 0.6);
+  /* Pointer line + knurl tick marks drawn on top of the metal body. */
+}
+/* The arc: a conic-gradient slice rotated to the knob's angle. --knob-rot is
+ * passed as an angle (e.g. 150deg), not a percentage, so the sweep is valid. */
+.jambuddy-knob::before {
+  content: "";
+  position: absolute;
+  inset: 6px;
+  border-radius: 9999px;
+  background:
+    conic-gradient(
+      from -135deg,
+      transparent 0deg,
+      transparent calc(var(--knob-rot, 0deg) - 6deg),
+      #12131b calc(var(--knob-rot, 0deg) - 6deg) var(--knob-rot, 0deg),
+      transparent var(--knob-rot, 0deg) 360deg
+    );
+  opacity: 0.9;
+}
+/* The pointer line itself (the "needle"). */
+.jambuddy-knob::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 6px;
+  height: 26px;
+  border-radius: 2px;
+  background: linear-gradient(180deg, #14161d, #3a3f4a 45%, #14161d);
+  box-shadow: 0 0 2px rgba(0, 0, 0, 0.8);
+  transform: translate(-50%, -100%) rotate(var(--knob-rot, 0deg));
+  transform-origin: 50% 100%;
+}
+/* Range thumb hidden — the pointer is drawn by ::after so the native thumb is
+   invisible; keep it transparent to preserve drag interaction. */
+.jambuddy-knob::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 0;
+  height: 0;
+}
+.jambuddy-knob::-moz-range-thumb {
+  width: 0;
+  height: 0;
+}
+
+/* The big trigger button */
+.jambuddy-trigger {
+  border-radius: 0.5rem;
+  border: none;
+  background: linear-gradient(180deg, #f4a261 0%, #e07b3a 100%);
+  color: #12131b;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 1rem;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  padding: 0.9rem 0;
+  cursor: pointer;
+  box-shadow: 0 2px 0 #a85a24;
+}
+.jambuddy-trigger:hover {
+  filter: brightness(1.05);
+}
+.jambuddy-trigger:disabled {
+  opacity: 0.5;
+  cursor: wait;
+}
+
+/* Big RED record button — a physical record arm with a glowing tip. */
+.jambuddy-record {
+  border-radius: 0.5rem;
+  border: 1px solid #7a1c1c;
+  background: linear-gradient(180deg, #d64545 0%, #a11f1f 55%, #7a1414 100%);
+  color: #ffe9e9;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 1rem;
+  font-weight: 800;
+  letter-spacing: 0.12em;
+  padding: 0.9rem 0;
+  cursor: pointer;
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.35),
+    inset 0 -3px 6px rgba(0, 0, 0, 0.4),
+    0 2px 0 #5c0f0f;
+  position: relative;
+}
+.jambuddy-record:hover {
+  filter: brightness(1.08);
+}
+.jambuddy-record[aria-pressed="true"] {
+  background: linear-gradient(180deg, #e05252 0%, #b52424 55%, #8a1616 100%);
+  box-shadow:
+    inset 0 2px 4px rgba(0, 0, 0, 0.55),
+    0 0 14px rgba(224, 60, 60, 0.6),
+    0 1px 0 #5c0f0f;
+  transform: translateY(1px);
+}
+.jambuddy-record:disabled {
+  opacity: 0.5;
+  cursor: wait;
+}
+
+/* Physical hardware toggle for the engine (API / Local). A labelled checkbox
+ * hidden inside; the visual is a metal slide switch with a chunky lever that
+ * travels between two detent positions (API left, Local right), matching the
+ * hardware-sampler aesthetic. Keyboard/screenreader usable via the input. */
+.engine-toggle {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.68rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+.engine-toggle input {
+  position: absolute;
+  opacity: 0;
+  width: 0;
+  height: 0;
+}
+/* The switch body — a recessed metal channel with a center detent notch. */
+.engine-toggle__switch {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  width: 6.5rem;
+  height: 2rem;
+  border-radius: 0.4rem;
+  background: linear-gradient(180deg, #4a4f5a 0%, #2c3038 60%, #1e2127 100%);
+  border: 1px solid #17191e;
+  box-shadow:
+    inset 0 2px 5px rgba(0, 0, 0, 0.7),
+    0 1px 1px rgba(255, 255, 255, 0.12);
+  padding: 0 0.35rem;
+}
+/* Labels pinned to each side of the lever travel. */
+.engine-toggle__label {
+  position: absolute;
+  top: 50%;
+  transform: translateY(-50%);
+  color: #8b92a0;
+  font-weight: 700;
+  z-index: 1;
+  pointer-events: none;
+}
+.engine-toggle__label--api {
+  left: 0.45rem;
+}
+.engine-toggle__label--local {
+  right: 0.3rem;
+}
+/* The chunky metal lever — slides to whichever side is active. */
+.engine-toggle__lever {
+  position: absolute;
+  top: 50%;
+  left: 0.3rem;
+  width: 2.6rem;
+  height: 1.5rem;
+  border-radius: 0.25rem;
+  background: linear-gradient(180deg, #f0e9dc 0%, #cfc7b8 40%, #a89f8e 100%);
+  border: 1px solid #6b6352;
+  box-shadow:
+    inset 0 1px 1px rgba(255, 255, 255, 0.7),
+    inset 0 -3px 5px rgba(0, 0, 0, 0.35),
+    0 2px 3px rgba(0, 0, 0, 0.5);
+  transform: translateY(-50%);
+  transition: left 0.18s cubic-bezier(0.34, 1.56, 0.64, 1);
+  cursor: pointer;
+}
+/* A grip groove on the lever. */
+.engine-toggle__lever::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: 1rem;
+  height: 3px;
+  border-radius: 2px;
+  background: rgba(0, 0, 0, 0.25);
+  box-shadow: 0 1px 0 rgba(255, 255, 255, 0.5);
+}
+/* Checked (API) -> lever slides left under the API label; active label glows. */
+.engine-toggle input:checked + .engine-toggle__switch .engine-toggle__lever {
+  left: 0.3rem;
+}
+.engine-toggle input:not(:checked) + .engine-toggle__switch .engine-toggle__lever {
+  left: calc(100% - 2.9rem);
+}
+.engine-toggle input:checked + .engine-toggle__switch .engine-toggle__label--api {
+  color: #f4a261;
+  text-shadow: 0 0 6px rgba(244, 162, 97, 0.6);
+}
+.engine-toggle input:not(:checked) + .engine-toggle__switch .engine-toggle__label--local {
+  color: #5fd38a;
+  text-shadow: 0 0 6px rgba(95, 211, 138, 0.6);
+}
+.engine-toggle input:focus-visible + .engine-toggle__switch {
+  outline: 3px solid var(--focus);
+  outline-offset: 2px;
+}
+.engine-toggle input:disabled + .engine-toggle__switch {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+:root {
+  --bg: #ffffff;
+  --fg: #1a1a1a;
+  --accent: #0066cc;
+  --focus: #ffd700;
+  --limb-kick: #d62828;
+  --limb-snare: #1d3557;
+  --limb-hihat: #f4a261;
+  --limb-ride: #2a9d8f;
+  --limb-crash: #e76f51;
+  --limb-china: #8338ec;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #1a1a1a;
+    --fg: #f0f0f0;
+    --accent: #66b2ff;
+  }
+}
+
+@media (prefers-contrast: more) {
+  :root {
+    --fg: #000000;
+    --bg: #ffffff;
+    --accent: #0000ee;
+    --focus: #ff00ff;
+  }
+}
+
+/* Always-visible focus outline — WCAG 2.4.7 */
+:focus-visible {
+  outline: 3px solid var(--focus);
+  outline-offset: 2px;
+}
+
+/* Skip links — pattern from docs/05-accessibility.md §Keyboard navigation */
+.skip-link {
+  position: absolute;
+  top: -40px;
+  left: 0;
+  background: var(--accent);
+  color: var(--bg);
+  padding: 0.5rem 1rem;
+  z-index: 100;
+}
+.skip-link:focus {
+  top: 0;
+}
+
+/* Reduced motion — docs/05-accessibility.md §Reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}

apps/web/app/layout.tsx

@@ -0,0 +1,31 @@
+import type { Metadata, Viewport } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Jam Buddy",
+  description:
+    "Jam Buddy — an AI music companion that listens to what you play and joins in, at your tempo, in the instrument you pick. Built for the Stability AI Challenge at Music Hackspace Montreal.",
+};
+
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+  themeColor: "#1a1a1a",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body className="min-h-screen bg-bg text-fg antialiased">
+        <a href="#main-content" className="skip-link">
+          Skip to main content
+        </a>
+        {children}
+      </body>
+    </html>
+  );
+}

apps/web/app/page.tsx

@@ -0,0 +1,628 @@
+"use client";
+
+import { useRef, useState } from "react";
+import {
+  buildPrompt,
+  GENRE_LABELS,
+  GENRES,
+  INPUT_INSTRUMENTS,
+  INPUT_INSTRUMENT_LABELS,
+  INSTRUMENTS,
+  INSTRUMENT_LABELS,
+  MOOD_LABELS,
+  MOODS,
+  type BuddyGenre,
+  type BuddyInstrument,
+  type BuddyMood,
+  type InputInstrument,
+} from "@/lib/jambuddy/prompt";
+import { parseMidi, isPercussion, midiDuration } from "@/lib/jambuddy/player";
+import { createMidiRecorder, recordedNotesAsFile, type MidiRecorder } from "@/lib/jambuddy/recorder";
+import { Visualizer } from "@/lib/jambuddy/visualizer";
+
+/**
+ * Jam Buddy — "you start playing, it joins in."
+ *
+ * A hardware-sampler-styled panel. The user sets the instrument (a knob), the
+ * style, and the tempo, optionally loads a MIDI take from a controller, then
+ * hits "JOIN IN" — the buddy responds at their tempo. The response plays back
+ * in the rack.
+ *
+ * Accessibility preserved: every knob is a labelled <input type=range> (keyboard
+ * operable + screenreader-readable), buttons have accessible names, and the
+ * status is announced via aria-live. Focus outline is the global :focus-visible.
+ */
+
+/* A rotary-style knob. Under the hood a labelled <input type=range> so it works
+ * with a keyboard and a screen reader, wrapped in a dark hardware look. */
+function Knob({
+  label,
+  value,
+  min,
+  max,
+  step,
+  onChange,
+  format = (v: number) => String(v),
+  disabled = false,
+  editable = false,
+}: {
+  label: string;
+  value: number;
+  min: number;
+  max: number;
+  step?: number;
+  onChange: (v: number) => void;
+  format?: (v: number) => string;
+  disabled?: boolean;
+  /** Render the readout as a typeable number input (e.g. exact tempo). */
+  editable?: boolean;
+}) {
+  const pct = ((value - min) / (max - min)) * 100;
+  // --knob-rot is an actual angle (degrees), NOT a percentage. CSS can't do
+  // calc(<percentage> * <angle>) — passing the degrees directly keeps the
+  // needle + arc in sync with the value.
+  const rot = `${pct * 3}deg`;
+  return (
+    <label className={`flex flex-col items-center gap-1 ${disabled ? "opacity-40" : ""}`}>
+      <span className="text-[10px] uppercase tracking-widest text-[#7f8c9b]">
+        {label}
+      </span>
+      <input
+        type="range"
+        min={min}
+        max={max}
+        step={step ?? 1}
+        value={value}
+        aria-label={label}
+        disabled={disabled}
+        onChange={(e) => onChange(Number(e.target.value))}
+        className="jambuddy-knob"
+        style={{ ["--knob-rot" as string]: rot }}
+      />
+      {editable ? (
+        <input
+          type="number"
+          min={min}
+          max={max}
+          step={step ?? 1}
+          value={value}
+          aria-label={`${label} value`}
+          disabled={disabled}
+          onChange={(e) => {
+            const v = e.target.value === "" ? min : Number(e.target.value);
+            onChange(Math.min(max, Math.max(min, v)));
+          }}
+          className="w-16 rounded border border-[#2a2d3d] bg-[#12131b] px-1 text-center font-mono text-sm font-bold text-[#e8e8f0]"
+        />
+      ) : (
+        <span className="font-mono text-sm font-bold text-[#e8e8f0]">
+          {disabled ? "from take" : format(value)}
+        </span>
+      )}
+    </label>
+  );
+}
+
+/* A trigger pad that selects an option and flashes as a visual affordance. */
+function Pad({
+  label,
+  selected,
+  onSelect,
+}: {
+  label: string;
+  selected: boolean;
+  onSelect: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onSelect}
+      aria-pressed={selected}
+      className={`jambuddy-pad ${selected ? "jambuddy-pad--on" : ""}`}
+    >
+      {label}
+    </button>
+  );
+}
+
+export default function HomePage() {
+  const [instrument, setInstrument] = useState<BuddyInstrument>("bass");
+  const [inputInstrument, setInputInstrument] = useState<InputInstrument>("other");
+  const [genre, setGenre] = useState<BuddyGenre>("metal");
+  const [mood, setMood] = useState<BuddyMood>("energetic");
+  const [bpm, setBpm] = useState(184);
+  const [midiFile, setMidiFile] = useState<File | null>(null);
+  const [midiBytes, setMidiBytes] = useState<ArrayBuffer | null>(null);
+  const [audioFile, setAudioFile] = useState<File | null>(null);
+  const [status, setStatus] = useState<string>("Ready.");
+  const [audioUrl, setAudioUrl] = useState<string | null>(null);
+  const [usedBpm, setUsedBpm] = useState<number | null>(null);
+  const [usedSeconds, setUsedSeconds] = useState<number | null>(null);
+  const [busy, setBusy] = useState(false);
+  // Generation backend. API (Stable Audio 3.0 Large) is default when the key is
+  // present — fast + better isolation, 26 credits/gen. Local = CPU small model,
+  // free, supports the negative prompt, slower.
+  const [mode, setMode] = useState<"api" | "local">("api");
+  // Live MIDI capture. recRef holds the active recorder; recording is a state
+  // so the big RED button reflects it.
+  const recRef = useRef<MidiRecorder | null>(null);
+  const [recording, setRecording] = useState(false);
+  // Object URL of the last recorded MIDI take (for save + piano-roll).
+  const [recordedMidiUrl, setRecordedMidiUrl] = useState<string | null>(null);
+
+  const { prompt, negativePrompt } = buildPrompt({
+    instrument,
+    inputInstrument,
+    genre,
+    mood,
+    bpm,
+  });
+
+  function fileToBase64(file: File): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => {
+        const result = reader.result as string;
+        const comma = result.indexOf(",");
+        resolve(comma >= 0 ? result.slice(comma + 1) : result);
+      };
+      reader.onerror = reject;
+      reader.readAsDataURL(file);
+    });
+  }
+
+  function fileToArrayBuffer(file: File): Promise<ArrayBuffer> {
+    return file.arrayBuffer();
+  }
+
+  /** Detect whether a take file is MIDI or audio from its name/MIME type. */
+  function isMidiFile(f: File): boolean {
+    return (
+      /\.mid$/i.test(f.name) ||
+      /\.midi$/i.test(f.name) ||
+      f.type === "audio/midi" ||
+      f.type === "audio/x-midi"
+    );
+  }
+
+  /** Handle a single uploaded take (MIDI or audio), auto-detecting the type. */
+  async function handleTakeFile(f: File | null) {
+    // One upload slot for either kind; picking a new file clears the old take.
+    setMidiFile(null);
+    setMidiBytes(null);
+    setAudioFile(null);
+    if (!f) {
+      setStatus("Ready.");
+      return;
+    }
+    if (isMidiFile(f)) {
+      setMidiFile(f);
+      const bytes = await fileToArrayBuffer(f);
+      setMidiBytes(bytes);
+      // Soft-default: if the MIDI has GM channel 9 notes, pre-select the
+      // "Drums" input-instrument pad. parseMidi throws on corrupt bytes; fall
+      // back to "other".
+      try {
+        setInputInstrument(parseMidi(bytes).some(isPercussion) ? "drums" : "other");
+      } catch {
+        setInputInstrument("other");
+      }
+      // Pre-fill the tempo knob from the take's tempo map (Option A: detect
+      // first, knob stays authoritative + editable).
+      await prefillTempo(f, "midi");
+      setStatus(
+        `Loaded ${f.name}. Tempo auto-detected (${bpm} BPM); adjust the knob if needed.`,
+      );
+    } else {
+      setAudioFile(f);
+      // Audio is heard by the buddy (audio-to-audio). Clear the MIDI-driven
+      // input-instrument default so the user's declaration reflects the audio.
+      setInputInstrument("other");
+      await prefillTempo(f, "audio");
+      setStatus(
+        `Loaded ${f.name}. Tempo auto-detected (${bpm} BPM); adjust the knob if needed.`,
+      );
+    }
+  }
+
+  /** Ask the server to detect BPM+duration and pre-fill the tempo knob. */
+  async function prefillTempo(f: File, kind: "midi" | "audio") {
+    try {
+      const base64 = await fileToBase64(f);
+      const res = await fetch("/api/jambuddy/detect", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(
+          kind === "midi" ? { midi: base64 } : { audio: base64, genre },
+        ),
+      });
+      if (res.ok) {
+        const data = (await res.json()) as { bpm?: number; duration?: number };
+        if (typeof data.bpm === "number" && data.bpm > 0) {
+          setBpm(Math.round(Math.max(40, Math.min(240, data.bpm))));
+        }
+        return data;
+      }
+    } catch {
+      /* detection is best-effort; knob keeps its current value */
+    }
+    return null;
+  }
+
+  /** Toggle live MIDI capture. On stop, the take is written as a .mid file and
+   * fed through the normal take pipeline (tempo detect + duration + input). */
+  async function toggleRecord() {
+    if (recording) {
+      // Stop: convert recorded notes to a .mid File and treat as a MIDI take.
+      const rec = recRef.current;
+      if (rec) {
+        const { notes, durationSec } = rec.stop();
+        rec.dispose();
+        recRef.current = null;
+        setRecording(false);
+        if (notes.length === 0) {
+          setStatus("Recording stopped — no notes captured.");
+          return;
+        }
+        // Use the current knob BPM (or 120) for the tempo map of the .mid.
+        const file = recordedNotesAsFile(notes, bpm || 120);
+        // Keep an object URL so the user can save the .mid and see its roll.
+        if (recordedMidiUrl) URL.revokeObjectURL(recordedMidiUrl);
+        setRecordedMidiUrl(URL.createObjectURL(file));
+        setStatus(
+          `Captured ${notes.length} notes (${durationSec.toFixed(1)}s). Detecting tempo…`,
+        );
+        await handleTakeFile(file);
+      } else {
+        setRecording(false);
+      }
+      return;
+    }
+    // Start: create the recorder + begin listening.
+    setStatus("Connecting to MIDI controller…");
+    try {
+      const rec = await createMidiRecorder();
+      recRef.current = rec;
+      rec.start();
+      setRecording(true);
+      setStatus("● RECORDING — play your take, then press stop.");
+    } catch (e) {
+      setStatus(`MIDI record unavailable: ${String(e)}`);
+    }
+  }
+
+  /** Download the last recorded MIDI take as a .mid file. */
+  function saveRecordedMidi() {
+    if (!recordedMidiUrl) {
+      setStatus("Record a take first, then save it.");
+      return;
+    }
+    const a = document.createElement("a");
+    a.href = recordedMidiUrl;
+    a.download = `jambuddy-live-capture-${new Date()
+      .toISOString()
+      .replace(/[-:]/g, "")
+      .replace(/\.\d+Z$/, "Z")}.mid`;
+    a.rel = "noopener";
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    setStatus("Saved your recorded MIDI take.");
+  }
+
+  async function joinIn() {
+    setBusy(true);
+    setStatus(
+      mode === "api"
+        ? "Producing… (Stable Audio API, ~20s)."
+        : "Producing… this can take a minute on CPU.",
+    );
+    setAudioUrl(null);
+    setUsedBpm(null);
+    setUsedSeconds(null);
+    try {
+      const payload: {
+        knobs: {
+          instrument: BuddyInstrument;
+          inputInstrument: InputInstrument;
+          genre: BuddyGenre;
+          mood: BuddyMood;
+          bpm: number;
+        };
+        bpm?: number;
+        midi?: string;
+        audio?: string;
+        duration?: number;
+        mode: "api" | "local";
+      } = { knobs: { instrument, inputInstrument, genre, mood, bpm }, mode };
+
+      if (midiFile) {
+        setStatus("Reading your MIDI take…");
+        const base64 = await fileToBase64(midiFile);
+        payload.midi = base64;
+        // Detect tempo from the take, and match its length so the response
+        // starts and ends together with it (in tempo).
+        delete payload.bpm;
+        if (midiBytes) payload.duration = Math.max(1, midiDuration(midiBytes));
+      } else if (audioFile) {
+        setStatus("Reading your audio take…");
+        const base64 = await fileToBase64(audioFile);
+        payload.audio = base64;
+        // Audio-to-audio: the buddy responds to the groove.
+        delete payload.bpm;
+      }
+
+      const res = await fetch("/api/jambuddy", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+      if (!res.ok) {
+        const err = await res.json().catch(() => null);
+        setStatus(`Production failed: ${err?.detail ?? err?.error ?? res.status}`);
+        return;
+      }
+      // The route returns the tempo it locked onto + the wall-clock generate time.
+      const headerBpm = res.headers.get("X-Jam-Buddy-BPM");
+      if (headerBpm) setUsedBpm(Math.round(Number(headerBpm)));
+      const headerTime = res.headers.get("X-Jam-Buddy-Time");
+      if (headerTime) setUsedSeconds(Number(headerTime) / 1000);
+      const blob = await res.blob();
+      setAudioUrl(URL.createObjectURL(blob));
+      setStatus("Done — your buddy produced a response.");
+    } catch (e) {
+      setStatus(`Error: ${String(e)}`);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <main
+      id="main-content"
+      className="mx-auto max-w-3xl px-4 py-8"
+      aria-labelledby="page-title"
+    >
+      <div className="jambuddy-rack rounded-2xl p-6 shadow-2xl">
+        <header className="mb-6 flex items-center justify-between border-b border-[#2a2d3d] pb-3">
+          <h1
+            id="page-title"
+            className="font-mono text-2xl font-bold tracking-tight text-[#e8e8f0]"
+          >
+            JAM <span className="text-[#f4a261]">BUDDY</span>
+          </h1>
+          <span className="rounded bg-[#2a2d3d] px-2 py-1 font-mono text-[10px] uppercase tracking-widest text-[#7f829c]">
+            rack • v0.1
+          </span>
+        </header>
+
+        {/* Instrument / trigger pads */}
+        <section aria-labelledby="pads-label" className="mb-6">
+          <h2
+            id="pads-label"
+            className="mb-2 font-mono text-[10px] uppercase tracking-widest text-[#7f829c]"
+          >
+            Instrument
+          </h2>
+          <div className="grid grid-cols-4 gap-2 sm:grid-cols-8">
+            {INSTRUMENTS.map((inst) => (
+              <Pad
+                key={inst}
+                label={INSTRUMENT_LABELS[inst]}
+                selected={instrument === inst}
+                onSelect={() => setInstrument(inst)}
+              />
+            ))}
+          </div>
+        </section>
+
+        {/* Knob row */}
+        <section
+          aria-label="Style controls"
+          className="mb-6 grid grid-cols-3 gap-4 rounded-xl bg-[#15161f] p-4"
+        >
+          <Knob
+            label="Genre"
+            value={GENRES.indexOf(genre)}
+            min={0}
+            max={GENRES.length - 1}
+            onChange={(v) => setGenre(GENRES[v] ?? "metal")}
+            format={(v) => GENRE_LABELS[GENRES[v] ?? "metal"] ?? ""}
+          />
+          <Knob
+            label="Mood"
+            value={MOODS.indexOf(mood)}
+            min={0}
+            max={MOODS.length - 1}
+            onChange={(v) => setMood(MOODS[v] ?? "energetic")}
+            format={(v) => MOOD_LABELS[MOODS[v] ?? "energetic"] ?? ""}
+          />
+          <Knob
+            label="Tempo"
+            value={bpm}
+            min={60}
+            max={220}
+            step={1}
+            onChange={setBpm}
+            format={(v) => `${v} BPM`}
+            editable
+          />
+        </section>
+
+        {/* Your-take-is knob — declares what instrument the user is playing
+            so the buddy can complement it (no MIR on input). */}
+        <section
+          aria-label="Your take"
+          className="mb-6 rounded bg-[#1f2130] p-4"
+        >
+          <h2 className="mb-2 font-mono text-[10px] uppercase tracking-widest text-[#7f829c]">
+            Your take is
+          </h2>
+          <p className="mb-2 text-[11px] text-[#7f829c]">
+            For MIDI we can&apos;t read the notes, so tell us what you&apos;re
+            playing — it helps the buddy complement (not duplicate) it. Audio is
+            heard directly (audio-to-audio).
+          </p>
+          <div className="grid grid-cols-3 gap-2 sm:grid-cols-6">
+            {INPUT_INSTRUMENTS.map((i) => (
+              <Pad
+                key={i}
+                label={INPUT_INSTRUMENT_LABELS[i]}
+                selected={inputInstrument === i}
+                onSelect={() => setInputInstrument(i)}
+              />
+            ))}
+          </div>
+        </section>
+
+        {/* Take input — MIDI or audio */}
+        <section
+          aria-labelledby="take-label"
+          className="mb-6 rounded bg-[#1f2130] p-4"
+        >
+          <h2
+            id="take-label"
+            className="mb-2 font-mono text-[10px] uppercase tracking-widest text-[#7f829c]"
+          >
+            Your take (optional)
+          </h2>
+          <p className="mb-2 text-[11px] text-[#7f829c]">
+            MIDI sets tempo + length; audio makes the buddy respond to your groove.
+            Drop either in the slot below.
+          </p>
+          <label className="flex flex-col gap-1">
+            <input
+              type="file"
+              accept=".mid,.midi,.wav,.mp3,.aiff,.flac,audio/midi,audio/x-midi,audio/*"
+              aria-label="Upload your take — MIDI or audio"
+              onChange={(e) => handleTakeFile(e.target.files?.[0] ?? null)}
+              className="block w-full rounded border border-[#2a2d3d] bg-[#12131b] px-3 py-2 text-sm text-[#c9c9d6] file:mr-3 file:rounded file:border-0 file:bg-[#f4a261] file:px-3 file:py-1 file:font-bold file:text-[#12131b]"
+            />
+          </label>
+          {midiFile && (
+            <p className="mt-2 text-xs text-[#7f829c]">
+              {midiFile.name} — MIDI: tempo + length detected from it.
+            </p>
+          )}
+          {audioFile && (
+            <p className="mt-2 text-xs text-[#7f829c]">
+              {audioFile.name} — audio: buddy responds to its groove (audio-to-audio).
+            </p>
+          )}
+        </section>
+
+        {/* Transport */}
+        <div className="mb-3 flex items-center gap-3">
+          <span className="font-mono text-[10px] uppercase tracking-widest text-[#7f829c]">
+            Engine
+          </span>
+          <label className="engine-toggle">
+            <input
+              type="checkbox"
+              checked={mode === "api"}
+              onChange={(e) => setMode(e.target.checked ? "api" : "local")}
+            />
+            <span className="engine-toggle__switch">
+              <span className="engine-toggle__label engine-toggle__label--api">API</span>
+              <span className="engine-toggle__lever" aria-hidden="true" />
+              <span className="engine-toggle__label engine-toggle__label--local">Local</span>
+            </span>
+          </label>
+          <span className="font-mono text-[10px] text-[#7f829c]">
+            {mode === "api"
+              ? "Stable Audio 3.0 Large · 26 credits/gen · ~20s"
+              : "Local CPU · free · supports negative prompt · slower"}
+          </span>
+        </div>
+        <div className="mb-2 flex items-center gap-4">
+          <button
+            type="button"
+            onClick={toggleRecord}
+            disabled={busy}
+            aria-pressed={recording}
+            aria-label={recording ? "Stop recording" : "Record from MIDI controller"}
+            className="jambuddy-record flex-1"
+          >
+            {recording ? "■ STOP" : "● RECORD"}
+          </button>
+          <button
+            type="button"
+            onClick={saveRecordedMidi}
+            disabled={!recordedMidiUrl || busy}
+            className="jambuddy-trigger flex-1"
+            style={{
+              background: "linear-gradient(180deg,#5fd38a 0%,#3aa55f 100%)",
+              boxShadow: "0 2px 0 #256b3f",
+            }}
+          >
+            SAVE MIDI
+          </button>
+          <button
+            type="button"
+            onClick={joinIn}
+            disabled={busy}
+            className="jambuddy-trigger flex-1"
+          >
+            {busy ? "PRODUCING…" : "JOIN IN"}
+          </button>
+          <div className="font-mono text-xs text-[#7f829c]">
+            <div className="uppercase tracking-widest">Prompt</div>
+            <div className="mt-1 max-w-[16rem] truncate text-[#e8e8f0]">
+              {prompt}
+            </div>
+            <div className="mt-1 opacity-60">neg: {negativePrompt}</div>
+          </div>
+        </div>
+
+        {/* Status + playback */}
+        <section
+          aria-live="polite"
+          aria-label="Status"
+          className="rounded bg-[#12131b] p-4"
+        >
+          <div className="flex items-center justify-between">
+            <span className="font-mono text-xs text-[#7f829c]">STATUS</span>
+            <span
+              className={`h-2 w-2 rounded-full ${
+                busy ? "bg-[#f4a261]" : audioUrl ? "bg-[#5fd38a]" : "bg-[#4a4d5e]"
+              }`}
+            />
+          </div>
+          <p className="mt-1 text-sm text-[#e8e8f0]">{status}</p>
+          {usedBpm !== null && (
+            <p className="mt-2 font-mono text-sm font-bold text-[#f4a261]">
+              Buddy tempo: {usedBpm} BPM
+            </p>
+          )}
+          {usedSeconds !== null && (
+            <p className="mt-1 font-mono text-xs text-[#7f829c]">
+              Generated in {usedSeconds.toFixed(1)}s
+            </p>
+          )}
+          {audioUrl && (
+            <audio controls src={audioUrl} className="mt-3 w-full">
+              Your browser does not support audio playback.
+            </audio>
+          )}
+        </section>
+
+        {/* Take + response visualizers */}
+        {(midiBytes || audioUrl) && (
+          <section
+            aria-label="Take and response"
+            className="mt-4 grid grid-cols-1 gap-4 sm:grid-cols-2"
+          >
+            <Visualizer
+              midiBytes={midiBytes}
+              label="Your take (MIDI piano-roll)"
+            />
+            <Visualizer
+              audioUrl={audioUrl}
+              label="Buddy response (waveform)"
+            />
+          </section>
+        )}
+      </div>
+    </main>
+  );
+}

apps/web/data/onomatopoeia.json

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "entries": [
+    {
+      "id": "skank-beat",
+      "patterns": ["tupatupatupa", "tupa-tupa-tupa", "chka-chka-chka", "tupa tupa tupa"],
+      "patternId": "skank",
+      "defaultCymbal": { "type": "hihat-open", "pattern": "upstrokes" },
+      "confidence": 0.9,
+      "notes": "Ska-style offbeat hi-hat upstrokes. The canonical demo phrase."
+    },
+    {
+      "id": "blast-beat",
+      "patterns": ["krrk-krrk-krrk", "krrk krrk krrk", "BLAM-BLAM-BLAM", "krkrkrkrk"],
+      "patternId": "blast-traditional",
+      "defaultIntensity": "brutal",
+      "confidence": 0.85,
+      "notes": "Traditional blast beat. Kick-snare alternation."
+    },
+    {
+      "id": "boom-bap",
+      "patterns": ["boom-bap", "boom bap", "boom-bap-boom-bap"],
+      "patternId": "hiphop-basic",
+      "confidence": 0.95
+    },
+    {
+      "id": "china-accent",
+      "patterns": ["tss", "chka"],
+      "patternId": "china-accent",
+      "defaultCymbal": { "type": "china", "pattern": "wash" }
+    },
+    {
+      "id": "ride-bell",
+      "patterns": ["ding-ding-ding", "ding ding ding", "ding-ding-ding-ding"],
+      "patternId": "ride-bell-8ths",
+      "defaultCymbal": { "type": "ride", "pattern": "bell" }
+    }
+  ]
+}

apps/web/data/patterns/d-beat.json

@@ -0,0 +1,28 @@
+{
+  "id": "d-beat",
+  "name": "D-Beat",
+  "description": "D-beat pattern at 180 BPM. Kick plays on every beat with 8th-note doubles, snare hits on 2 and 4, ride bell plays steady 8ths throughout. Common in Discharge, Entombed, and Scandinavian crust punk.",
+  "tags": ["metal", "punk", "discharge", "entombed", "crust", "fast"],
+  "genre": "metal",
+  "defaultTempo": 180,
+  "defaultBars": 1,
+  "swingRatio": 0,
+  "hits": [
+    { "position": 0.0,   "limb": "kick",      "velocity": 110 },
+    { "position": 0.125, "limb": "kick",      "velocity": 80  },
+    { "position": 0.25,  "limb": "snare",     "velocity": 100 },
+    { "position": 0.375, "limb": "kick",      "velocity": 80  },
+    { "position": 0.5,   "limb": "kick",      "velocity": 110 },
+    { "position": 0.625, "limb": "kick",      "velocity": 80  },
+    { "position": 0.75,  "limb": "snare",     "velocity": 100 },
+    { "position": 0.875, "limb": "kick",      "velocity": 80  },
+    { "position": 0.0,   "limb": "ride-bell", "velocity": 70  },
+    { "position": 0.125, "limb": "ride-bell", "velocity": 70  },
+    { "position": 0.25,  "limb": "ride-bell", "velocity": 70  },
+    { "position": 0.375, "limb": "ride-bell", "velocity": 70  },
+    { "position": 0.5,   "limb": "ride-bell", "velocity": 70  },
+    { "position": 0.625, "limb": "ride-bell", "velocity": 70  },
+    { "position": 0.75,  "limb": "ride-bell", "velocity": 70  },
+    { "position": 0.875, "limb": "ride-bell", "velocity": 70  }
+  ]
+}

apps/web/data/patterns/skank.json

@@ -0,0 +1,20 @@
+{
+  "id": "skank",
+  "name": "Skank Beat",
+  "description": "Skank beat at 120 BPM. Kick on 1 and 3, snare on 2 and 4, hi-hat plays on every upbeat — the 'and' of each beat. Ska upstroke feel.",
+  "tags": ["ska", "punk", "upstrokes", "offbeat"],
+  "genre": "punk",
+  "defaultTempo": 120,
+  "defaultBars": 1,
+  "swingRatio": 0,
+  "hits": [
+    { "position": 0.0,   "limb": "kick",  "velocity": 100 },
+    { "position": 0.5,   "limb": "kick",  "velocity": 100 },
+    { "position": 0.25,  "limb": "snare", "velocity": 100 },
+    { "position": 0.75,  "limb": "snare", "velocity": 100 },
+    { "position": 0.125, "limb": "hihat", "velocity": 80 },
+    { "position": 0.375, "limb": "hihat", "velocity": 80 },
+    { "position": 0.625, "limb": "hihat", "velocity": 80 },
+    { "position": 0.875, "limb": "hihat", "velocity": 80 }
+  ]
+}

apps/web/lib/jambuddy/player.ts

@@ -0,0 +1,209 @@
+/**
+ * Jam Buddy playback.
+ *
+ * Plays the user's MIDI take and the buddy's generated response TOGETHER, in
+ * tempo, via the Web Audio API.
+ *
+ * - The MIDI take is rendered to audio with a lightweight synth (an oscillator
+ *   per note) so it's audible as "your" part, distinct from the buddy.
+ * - The generated response is a decoded AudioBuffer (the buddy's WAV).
+ * - Both are scheduled on the SAME AudioContext clock starting together, so
+ *   they stay in sync.
+ *
+ * This module is browser-only (window.AudioContext). It does not run under
+ * Node — keep all Web Audio in here and call from the page.
+ */
+
+import { Midi } from "@tonejs/midi";
+
+/** A parsed note: absolute start time (sec), midi note, velocity 0-1. */
+export interface ParsedNote {
+  time: number;
+  midi: number;
+  duration: number;
+  velocity: number;
+  /** GM channel 0-15; 9 = percussion. Used to route drums to a click. */
+  channel: number;
+}
+
+/** Parse a MIDI file's bytes into playable notes (+ duration). */
+export function parseMidi(bytes: ArrayBuffer): ParsedNote[] {
+  const midi = new Midi(bytes);
+  const notes: ParsedNote[] = [];
+  for (const track of midi.tracks) {
+    // tonejs exposes the channel on the Track (a plain number), not each Note.
+    const channel = track.channel ?? 0;
+    for (const note of track.notes) {
+      notes.push({
+        time: note.time,
+        midi: note.midi,
+        duration: note.duration,
+        velocity: note.velocity,
+        channel,
+      });
+    }
+  }
+  notes.sort((a, b) => a.time - b.time);
+  return notes;
+}
+
+/**
+ * Is this a percussion note (GM channel 9)? Drums render as a percussive
+ * click/noise burst so they're audible alongside the produced WAV, instead
+ * of a low thin oscillator that gets buried.
+ */
+export function isPercussion(note: ParsedNote): boolean {
+  return note.channel === 9;
+}
+
+/** midi note -> frequency in Hz. */
+export function midiToFreq(n: number): number {
+  return 440 * Math.pow(2, (n - 69) / 12);
+}
+
+/**
+ * Schedule a MIDI note as an audible source through a gain envelope.
+ * Percussion (GM channel 9) renders as a short noise-burst click so drum hits
+ * cut through the produced WAV; pitched notes render as a short oscillator.
+ */
+function scheduleNote(
+  ctx: AudioContext,
+  note: ParsedNote,
+  dest: AudioNode,
+  when: number,
+) {
+  const gain = ctx.createGain();
+  const dur = Math.max(0.05, note.duration);
+  const vel = Math.max(0.2, note.velocity); // floor so quiet notes stay audible
+
+  if (isPercussion(note)) {
+    // Short noise burst (kick/snare-ish) so drum hits are clearly heard.
+    const len = Math.max(0.05, Math.min(0.15, dur));
+    const buf = ctx.createBuffer(1, Math.ceil(len * ctx.sampleRate), ctx.sampleRate);
+    const data = buf.getChannelData(0);
+    for (let i = 0; i < data.length; i++) {
+      data[i] = (Math.random() * 2 - 1) * Math.exp(-(i / data.length) * 6);
+    }
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    gain.gain.setValueAtTime(0, when);
+    gain.gain.linearRampToValueAtTime(vel * 0.7, when + 0.005);
+    gain.gain.exponentialRampToValueAtTime(0.0001, when + len);
+    src.connect(gain);
+    gain.connect(dest);
+    src.start(when);
+    src.stop(when + len + 0.02);
+    return;
+  }
+
+  const osc = ctx.createOscillator();
+  osc.type = "triangle";
+  osc.frequency.value = midiToFreq(note.midi);
+
+  gain.gain.setValueAtTime(0, when);
+  gain.gain.linearRampToValueAtTime(vel * 0.5, when + 0.01);
+  gain.gain.exponentialRampToValueAtTime(0.0001, when + dur);
+
+  osc.connect(gain);
+  gain.connect(dest);
+  osc.start(when);
+  osc.stop(when + dur + 0.02);
+}
+
+/**
+ * Play the MIDI take and the buddy WAV together.
+ *
+ * @param midiBytes      the user's MIDI take (raw bytes)
+ * @param buddyAudioUrl  the generated response WAV (object URL)
+ * @param when           optional start offset in sec (default: immediately)
+ * @returns an object with stop(), and promise resolving when both finish.
+ */
+export async function playTogether(
+  midiBytes: ArrayBuffer,
+  buddyAudioUrl: string,
+): Promise<{ stop: () => void; done: Promise<void> }> {
+  const ctx = new AudioContext();
+  await ctx.resume();
+
+  // Decode the buddy WAV into a buffer.
+  const resp = await fetch(buddyAudioUrl);
+  const wav = await resp.arrayBuffer();
+  const buddyBuffer = await ctx.decodeAudioData(wav);
+
+  const master = ctx.createGain();
+  master.gain.value = 0.8;
+  master.connect(ctx.destination);
+
+  const notes = parseMidi(midiBytes);
+  const startAt = ctx.currentTime + 0.1;
+
+  // Schedule the buddy at the same clock time.
+  const buddySrc = ctx.createBufferSource();
+  buddySrc.buffer = buddyBuffer;
+  buddySrc.connect(master);
+  buddySrc.start(startAt);
+
+  // Schedule the MIDI notes.
+  for (const note of notes) {
+    scheduleNote(ctx, note, master, startAt + note.time);
+  }
+
+  const buddyEnd = startAt + buddyBuffer.duration;
+  const lastMidiTime = notes.length ? (notes[notes.length - 1]?.time ?? 0) : 0;
+  const midiEnd = startAt + lastMidiTime + 1;
+  const end = Math.max(buddyEnd, midiEnd);
+
+  const done = new Promise<void>((resolve) => {
+    setTimeout(() => {
+      try {
+        ctx.close();
+      } catch {
+        /* already closed */
+      }
+      resolve();
+    }, Math.max(0, (end - ctx.currentTime) * 1000) + 200);
+  });
+
+  return {
+    stop: () => {
+      try {
+        buddySrc.stop();
+        ctx.close();
+      } catch {
+        /* ignore */
+      }
+    },
+    done,
+  };
+}
+
+/** Get the detected tempo from a MIDI file (for display). */
+export function midiTempo(buf: ArrayBuffer): number {
+  try {
+    const midi = new Midi(buf);
+    const t = midi.header.tempos[0]?.bpm;
+    return t ? Math.round(t) : 120;
+  } catch {
+    return 120;
+  }
+}
+
+/**
+ * Get the total duration (seconds) of a MIDI file — the time of the last note
+ * end. This is what the generated response must match so the take and the
+ * buddy are the same length and stay in tempo together.
+ */
+export function midiDuration(buf: ArrayBuffer): number {
+  try {
+    const midi = new Midi(buf);
+    let end = 0;
+    for (const track of midi.tracks) {
+      for (const note of track.notes) {
+        end = Math.max(end, note.time + note.duration);
+      }
+    }
+    return end;
+  } catch {
+    return 30;
+  }
+}

apps/web/lib/jambuddy/prompt.ts

@@ -0,0 +1,287 @@
+/**
+ * Jam Buddy prompt builder.
+ *
+ * Builds the SA3 text prompt from the user's "knobs", following the official
+ * Stable Audio 3 prompt guide (docs/guides/prompting.md → "Stem & Solo
+ * Instrument Prompting"):
+ *
+ *   Key elements: TrackType: Instrument, Instrument/Stem, Genre, Mood & energy,
+ *   BPM.
+ *
+ * The guide's recommended structure for an isolated instrument is:
+ *   TrackType: Instrument, {instrument}, {genre}, {mood}, {BPM} BPM
+ *
+ * We also append "studio recording" (positive) and use "field recording" as the
+ * negative prompt — the training data is Freesound/AudioSparx (full of field
+ * recordings), so steering away from that improves quality.
+ *
+ * Pure function — no DOM, no I/O. Test this thoroughly.
+ */
+
+export type BuddyInstrument =
+  | "bass"
+  | "lead"
+  | "rhythm"
+  | "synth"
+  | "drums"
+  | "sax"
+  | "cleanguitar"
+  | "overdrivenguitar";
+
+/**
+ * What the user IS playing on their take. SA3 has no MIR — it cannot read the
+ * input MIDI/audio to know what's already there. The user declares it, which
+ * (a) gives the buddy context about what to complement, and (b) honestly
+ * acknowledges the model limit. "other" = default, no specific declaration.
+ */
+export type InputInstrument =
+  | "drums"
+  | "bass"
+  | "guitar"
+  | "keys"
+  | "vocals"
+  | "other";
+
+export type BuddyGenre =
+  | "metal"
+  | "rock"
+  | "punk"
+  | "hiphop"
+  | "edm"
+  | "jazz"
+  | "pop"
+  | "any";
+
+export type BuddyMood =
+  | "energetic"
+  | "chill"
+  | "dark"
+  | "bright"
+  | "aggressive"
+  | "melodic";
+
+/** Instrument → AudioSparx `Instruments:` tag fragment (the "knob" options). */
+export const INSTRUMENT_PROMPTS: Readonly<Record<BuddyInstrument, string>> = {
+  bass: "Bass Guitar, a grooving bass line, tight and in the pocket",
+  lead: "Lead Guitar, a soaring melodic lead guitar riff",
+  rhythm: "Rhythm Guitar, tight palm-muted power chords",
+  synth: "Synth, a warm atmospheric pad",
+  drums: "Drums, a punchy drum groove, kick and snare locked in",
+  sax: "Saxophone, a warm breathy saxophone line with a rich tone",
+  cleanguitar: "Clean Guitar, bright chimey clean electric guitar arpeggios",
+  overdrivenguitar: "Overdriven Guitar, a gritty overdriven guitar riff with crunch",
+};
+
+/** Genre → AudioSparx `Genre:` tag. Matches the model's training vocab. */
+export const GENRE_PROMPTS: Readonly<Record<BuddyGenre, string>> = {
+  metal: "Heavy Metal",
+  rock: "Rock",
+  punk: "Punk",
+  hiphop: "Hip Hop",
+  edm: "Electronic Dance Music",
+  jazz: "Jazz",
+  pop: "Pop",
+  any: "",
+};
+
+/** Mood → AudioSparx `Moods:` tag. */
+export const MOOD_PROMPTS: Readonly<Record<BuddyMood, string>> = {
+  energetic: "Energetic",
+  chill: "Relaxed",
+  dark: "Dark",
+  bright: "Uplifting",
+  aggressive: "Aggressive",
+  melodic: "Melodic",
+};
+
+/** Negative-prompt tokens always applied (full-mix steer). */
+const BASE_NEGATIVES: readonly string[] = [
+  "other instruments", "full band", "mixed ensemble", "vocals",
+  "singing", "chords", "crowd", "noise", "field recording",
+];
+
+/**
+ * SA3 model per instrument. Drums force `small-sfx` — it yields clean isolated
+ * drum hits, not full-mix texture (verified: sfx is sparse, ~1.2 hits/sec,
+ * clean single hits vs music's dense smear). Everything else uses `small-music`
+ * for musical phrases.
+ */
+export const MODEL_FOR_INSTRUMENT: Readonly<Record<BuddyInstrument, string>> = {
+  bass: "small-music",
+  lead: "small-music",
+  rhythm: "small-music",
+  synth: "small-music",
+  drums: "small-sfx",
+  sax: "small-music",
+  cleanguitar: "small-music",
+  overdrivenguitar: "small-music",
+};
+
+export interface BuddyKnobs {
+  instrument: BuddyInstrument;
+  /** What the user is playing on the take. Helps SA3 complement, not duplicate. */
+  inputInstrument: InputInstrument;
+  genre: BuddyGenre;
+  mood: BuddyMood;
+  bpm: number;
+}
+
+export interface BuddyPrompt {
+  /** Positive prompt for SA3. */
+  prompt: string;
+  /** Negative prompt for SA3. */
+  negativePrompt: string;
+}
+
+/**
+ * Build the SA3 prompt from the knobs.
+ *
+ * Structure follows the official Stable Audio 3 prompt guide — the model is
+ * trained on Freesound/AudioSparx metadata, so prompts that use the AudioSparx
+ * tag vocabulary (`Genre:`, `Moods:`, `Instruments:`) adhere best:
+ *
+ *   TrackType: Music, VocalType: Instrumental, Genre: {genre},
+ *   Moods: {mood}, Instruments: {instrument}, {BPM} BPM, studio recording
+ *
+ * `TrackType: Music, VocalType: Instrumental` is the documented prefix for
+ * music generation (it's what the training metadata prepends) and materially
+ * improves quality/adherence vs. the old `TrackType: Instrument`.
+ */
+export function buildPrompt(knobs: BuddyKnobs): BuddyPrompt {
+  const parts: string[] = ["TrackType: Music, VocalType: Instrumental"];
+
+  const genre = GENRE_PROMPTS[knobs.genre];
+  if (genre) parts.push(`Genre: ${genre}`);
+
+  const mood = MOOD_PROMPTS[knobs.mood];
+  parts.push(`Moods: ${mood}`);
+
+  const instrument = INSTRUMENT_PROMPTS[knobs.instrument];
+  parts.push(`Instruments: ${instrument}`);
+
+  const bpm = Math.max(40, Math.min(240, Math.round(knobs.bpm)));
+  parts.push(`${bpm} BPM`, "studio recording");
+
+  // Build the negative prompt only — DO NOT add "avoid ..." to the positive
+  // prompt. SA3 is trained on AudioSparx tag vocab; free-form "avoid drums"
+  // would be out-of-vocab noise that dilutes the metadata header. The
+  // negative prompt is the correct place to steer away from the user's input
+  // instrument, and SA3 reads it as a hard constraint.
+  const negatives = [...BASE_NEGATIVES];
+  if (knobs.instrument !== "drums") negatives.push("percussion");
+  if (knobs.inputInstrument && knobs.inputInstrument !== "other") {
+    const ctx = INPUT_INSTRUMENT_PROMPTS[knobs.inputInstrument];
+    // Only negate the user's instrument when it's a DIFFERENT family from
+    // the buddy. e.g. buddy=lead (lead guitar) + input=guitar would steer
+    // SA3 away from ALL guitars including the buddy's. Compare nouns, not
+    // strings: drop the negation when the input noun overlaps the buddy's
+    // noun family.
+    if (ctx && !buddyInstrumentFamilyMatches(knobs.instrument, ctx)) {
+      negatives.push(ctx);
+    }
+  }
+  const negativePrompt = negatives.join(", ");
+
+  return {
+    prompt: parts.join(", "),
+    negativePrompt,
+  };
+}
+
+/**
+ * Does the buddy instrument's noun family overlap with the user's input
+ * noun? Used to avoid negating an instrument family the buddy is part of.
+ *
+ * e.g. buddy=lead ("lead guitar"), input=guitar ("guitar") — overlap, so we
+ * do NOT add "guitar" to the negative, since it would steer SA3 away from
+ * the buddy itself.
+ */
+function buddyInstrumentFamilyMatches(
+  instrument: BuddyInstrument,
+  inputNoun: string,
+): boolean {
+  const family: Readonly<Record<BuddyInstrument, string>> = {
+    bass: "bass",
+    lead: "guitar",
+    rhythm: "guitar",
+    synth: "synth",
+    drums: "drums",
+    sax: "sax",
+    cleanguitar: "guitar",
+    overdrivenguitar: "guitar",
+  };
+  return family[instrument] === inputNoun;
+}
+
+/** The knob options, for rendering dropdowns. */
+export const INSTRUMENTS: readonly BuddyInstrument[] = [
+  "bass",
+  "lead",
+  "rhythm",
+  "synth",
+  "drums",
+  "sax",
+  "cleanguitar",
+  "overdrivenguitar",
+];
+/** Input-instrument vocab (what the user is playing on the take). */
+export const INPUT_INSTRUMENTS: readonly InputInstrument[] = [
+  "drums",
+  "bass",
+  "guitar",
+  "keys",
+  "vocals",
+  "other",
+];
+/** Display labels for the input-instrument knob (AudioSparx vocab where possible). */
+export const INPUT_INSTRUMENT_LABELS: Readonly<Record<InputInstrument, string>> = {
+  drums: "Drums",
+  bass: "Bass",
+  guitar: "Guitar",
+  keys: "Keys / Synth",
+  vocals: "Vocals",
+  other: "Other / mixed",
+};
+/** Input-instrument → short AudioSparx-style noun for the prompt. */
+export const INPUT_INSTRUMENT_PROMPTS: Readonly<Record<InputInstrument, string>> = {
+  drums: "drums",
+  bass: "bass",
+  guitar: "guitar",
+  keys: "keys",
+  vocals: "vocals",
+  other: "",
+};
+export const GENRES: readonly BuddyGenre[] = [
+  "metal",
+  "rock",
+  "punk",
+  "hiphop",
+  "edm",
+  "jazz",
+  "pop",
+  "any",
+];
+export const MOODS: readonly BuddyMood[] = [
+  "energetic",
+  "chill",
+  "dark",
+  "bright",
+  "aggressive",
+  "melodic",
+];
+/** Human-friendly knob labels. The enum stays lowercase for wire-format
+ * stability; the UI reads these for display. AudioSparx vocab where possible. */
+export const GENRE_LABELS: Readonly<Record<BuddyGenre, string>> = {
+  metal: "Heavy Metal", rock: "Rock", punk: "Punk Rock", hiphop: "Hip Hop",
+  edm: "Electronic", jazz: "Jazz", pop: "Pop", any: "Any",
+};
+export const MOOD_LABELS: Readonly<Record<BuddyMood, string>> = {
+  energetic: "Energetic", chill: "Chill", dark: "Dark", bright: "Bright",
+  aggressive: "Aggressive", melodic: "Melodic",
+};
+/** Human-friendly labels for the buddy-instrument pads. */
+export const INSTRUMENT_LABELS: Readonly<Record<BuddyInstrument, string>> = {
+  bass: "Bass", lead: "Lead Guitar", rhythm: "Rhythm Guitar", synth: "Synth",
+  drums: "Drums", sax: "Sax", cleanguitar: "Clean Guitar",
+  overdrivenguitar: "Overdriven Guitar",
+};

apps/web/lib/jambuddy/recorder.ts

@@ -0,0 +1,156 @@
+/**
+ * Web MIDI capture for Jam Buddy.
+ *
+ * Listens to a connected MIDI input (a controller the user is playing),
+ * records note-on/note-off events with timestamps, and converts them into a
+ * Standard MIDI File (.mid) so the take feeds the existing upload pipeline
+ * (tempo auto-detect + duration + generation).
+ *
+ * Browser-only (Web MIDI API). Keep all MIDI access here, call from the page.
+ */
+
+import { Midi } from "@tonejs/midi";
+
+export interface RecordedNote {
+  /** Absolute time (seconds) from the recording start. */
+  time: number;
+  midi: number;
+  velocity: number;
+  /** GM channel the message arrived on (0-15; 9 = percussion). */
+  channel: number;
+}
+
+export interface MidiRecorder {
+  start(): void;
+  stop(): { notes: RecordedNote[]; durationSec: number };
+  isActive(): boolean;
+  /** Detach the MIDI listener (call when leaving the page / no longer needed). */
+  dispose(): void;
+}
+
+/**
+ * Build a Standard MIDI File byte buffer from recorded notes + a detected BPM.
+ * Single track, tempo meta at t=0, one note-on/note-off pair per event in
+ * PPQ-relative ticks. Reuses @tonejs/midi so we don't hand-roll SMF bytes.
+ */
+export function recordedNotesToMidi(
+  notes: RecordedNote[],
+  bpm: number,
+): Uint8Array {
+  const midi = new Midi();
+  midi.header.setTempo(60_000_000 / bpm);
+  midi.header.timeSignatures = [{ ticks: 0, timeSignature: [4, 4] }];
+
+  // Group by channel: a separate track per GM channel so percussion (9) and
+  // pitched notes don't collide.
+  const channels = [...new Set(notes.map((n) => n.channel))];
+  const byChannel = new Map<number, RecordedNote[]>();
+  for (const ch of channels) byChannel.set(ch, []);
+  for (const n of notes) byChannel.get(n.channel)!.push(n);
+
+  const ppq = 480;
+  for (const [ch, chNotes] of byChannel) {
+    const track = midi.addTrack();
+    track.channel = ch;
+    track.name = `Capture ch${ch}`;
+    for (const n of [...chNotes].sort((a, b) => a.time - b.time)) {
+      const ticks = Math.max(0, Math.round((n.time / 60) * bpm * ppq));
+      const durTicks = Math.max(1, Math.round((0.1 / 60) * bpm * ppq));
+      track.addNote({
+        midi: n.midi,
+        ticks,
+        durationTicks: durTicks,
+        velocity: Math.max(0.01, Math.min(1, n.velocity / 127)),
+      });
+    }
+  }
+  return midi.toArray();
+}
+
+/** Build a .mid File (for the take upload slot). */
+export function recordedNotesAsFile(
+  notes: RecordedNote[],
+  bpm: number,
+): File {
+  const bytes = recordedNotesToMidi(notes, bpm);
+  const ts = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+  return new File(
+    [new Uint8Array(bytes)],
+    `jambuddy-live-capture-${ts}.mid`,
+    { type: "audio/midi" },
+  );
+}
+
+/**
+ * Create a recorder bound to a MIDI input. Requests MIDI access (user gesture
+ * required in some browsers). Returns a started recorder + the chosen input.
+ *
+ * If `preferredDeviceName` is given, use that input; otherwise the first
+ * available. Throws if Web MIDI is unsupported or no input is available.
+ */
+export async function createMidiRecorder(
+  preferredDeviceName?: string,
+): Promise<MidiRecorder> {
+  if (typeof navigator === "undefined" || !("requestMIDIAccess" in navigator)) {
+    throw new Error("Web MIDI is not supported in this browser (try Chrome/Edge).");
+  }
+
+  const access = await navigator.requestMIDIAccess();
+  const inputs = [...access.inputs.values()];
+  if (inputs.length === 0) {
+    throw new Error("No MIDI input device found. Connect a controller.");
+  }
+  const input =
+    inputs.find((i) => i.name === preferredDeviceName) ??
+    inputs[0] ??
+    null;
+  if (!input) {
+    throw new Error("No MIDI input device found. Connect a controller.");
+  }
+
+  let active = false;
+  let startTime = 0;
+  const notes: RecordedNote[] = [];
+
+  const onMessage = (e: MIDIMessageEvent) => {
+    if (!active || !e.data) return;
+    const status = e.data[0];
+    const midi = e.data[1];
+    const vel = e.data[2];
+    if (status === undefined || midi === undefined || vel === undefined) return;
+    const cmd = status & 0xf0;
+    const channel = status & 0x0f;
+    if (cmd === 0x90 && vel > 0) {
+      notes.push({
+        time: (performance.now() - startTime) / 1000,
+        midi,
+        velocity: vel,
+        channel,
+      });
+    }
+  };
+  input.addEventListener("midimessage", onMessage);
+
+  return {
+    start() {
+      startTime = performance.now();
+      notes.length = 0;
+      active = true;
+    },
+    stop() {
+      active = false;
+      return {
+        notes: [...notes],
+        durationSec:
+          notes.length > 0
+            ? (performance.now() - startTime) / 1000
+            : 0,
+      };
+    },
+    isActive: () => active,
+    dispose() {
+      active = false;
+      input.removeEventListener("midimessage", onMessage);
+    },
+  };
+}

apps/web/lib/jambuddy/visualizer.tsx

@@ -0,0 +1,195 @@
+"use client";
+
+/**
+ * Jam Buddy take visualizer.
+ *
+ * Renders the user's take and the buddy's response on a canvas:
+ *  - MIDI  -> a piano-roll (notes as bars over time, pitch on the y-axis).
+ *  - audio -> a real waveform (min/max peaks over time).
+ *
+ * MIDI has no waveform (it's note data, not audio), so the honest visual for a
+ * MIDI take is a piano-roll; audio gets the waveform. Both share a time axis so
+ * you can compare the take and the response side by side.
+ */
+
+import { useEffect, useRef } from "react";
+import { parseMidi, type ParsedNote } from "./player";
+
+interface VisualizerProps {
+  /** MIDI bytes -> piano-roll. Mutually exclusive with audioUrl. */
+  midiBytes?: ArrayBuffer | null;
+  /** Audio object URL -> waveform. Mutually exclusive with midiBytes. */
+  audioUrl?: string | null;
+  /** Optional label shown above the canvas. */
+  label?: string;
+  /** Height of the canvas in px. */
+  height?: number;
+}
+
+const NOTE_MIN = 21; // A0
+const NOTE_MAX = 108; // C8
+
+/** Draw a piano-roll of MIDI notes onto a canvas. */
+function drawPianoRoll(
+  canvas: HTMLCanvasElement,
+  notes: ParsedNote[],
+  duration: number,
+) {
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return;
+  const dpr = window.devicePixelRatio || 1;
+  const w = canvas.clientWidth;
+  const h = canvas.clientHeight;
+  canvas.width = w * dpr;
+  canvas.height = h * dpr;
+  ctx.scale(dpr, dpr);
+
+  ctx.fillStyle = "#12131b";
+  ctx.fillRect(0, 0, w, h);
+
+  if (notes.length === 0 || duration <= 0) {
+    ctx.fillStyle = "#7f829c";
+    ctx.font = "12px ui-monospace, monospace";
+    ctx.textAlign = "center";
+    ctx.fillText("no notes", w / 2, h / 2);
+    return;
+  }
+
+  const pad = 8;
+  const plotW = w - pad * 2;
+  const plotH = h - pad * 2;
+  const span = NOTE_MAX - NOTE_MIN;
+
+  // Grid lines every octave.
+  ctx.strokeStyle = "#2a2d3d";
+  ctx.lineWidth = 1;
+  for (let n = NOTE_MIN; n <= NOTE_MAX; n += 12) {
+    const y = pad + (1 - (n - NOTE_MIN) / span) * plotH;
+    ctx.beginPath();
+    ctx.moveTo(pad, y);
+    ctx.lineTo(w - pad, y);
+    ctx.stroke();
+  }
+
+  // Notes as bars.
+  const maxTime = Math.max(duration, ...notes.map((n) => n.time + n.duration));
+  for (const n of notes) {
+    const x = pad + (n.time / maxTime) * plotW;
+    const bw = Math.max(2, (n.duration / maxTime) * plotW);
+    const y = pad + (1 - (n.midi - NOTE_MIN) / span) * plotH;
+    const bh = Math.max(2, plotH / span);
+    ctx.fillStyle = n.channel === 9 ? "#f4a261" : "#5fd38a";
+    ctx.fillRect(x, y - bh, bw, bh);
+  }
+}
+
+/** Draw a waveform (min/max peaks) of an AudioBuffer onto a canvas. */
+function drawWaveform(
+  canvas: HTMLCanvasElement,
+  buffer: AudioBuffer,
+) {
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return;
+  const dpr = window.devicePixelRatio || 1;
+  const w = canvas.clientWidth;
+  const h = canvas.clientHeight;
+  canvas.width = w * dpr;
+  canvas.height = h * dpr;
+  ctx.scale(dpr, dpr);
+
+  ctx.fillStyle = "#12131b";
+  ctx.fillRect(0, 0, w, h);
+
+  const data = buffer.getChannelData(0);
+  const step = Math.ceil(data.length / w);
+  const amp = h / 2;
+  ctx.fillStyle = "#5fd38a";
+  for (let x = 0; x < w; x++) {
+    let min = 1;
+    let max = -1;
+    for (let i = 0; i < step; i++) {
+      const v = data[x * step + i];
+      if (v === undefined) continue;
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+    const y1 = amp + min * amp;
+    const y2 = amp + max * amp;
+    ctx.fillRect(x, y1, 1, Math.max(1, y2 - y1));
+  }
+}
+
+export function Visualizer({
+  midiBytes,
+  audioUrl,
+  label,
+  height = 120,
+}: VisualizerProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    if (midiBytes) {
+      let notes: ParsedNote[] = [];
+      let duration = 0;
+      try {
+        notes = parseMidi(midiBytes);
+        duration = notes.reduce(
+          (m, n) => Math.max(m, n.time + n.duration),
+          0,
+        );
+      } catch {
+        /* corrupt bytes -> empty roll */
+      }
+      drawPianoRoll(canvas, notes, duration);
+      return;
+    }
+
+    if (audioUrl) {
+      const ctx = new AudioContext();
+      fetch(audioUrl)
+        .then((r) => r.arrayBuffer())
+        .then((buf) => ctx.decodeAudioData(buf))
+        .then((audio) => {
+          drawWaveform(canvas, audio);
+          ctx.close();
+        })
+        .catch(() => {
+          const c = canvas.getContext("2d");
+          if (c) {
+            c.fillStyle = "#12131b";
+            c.fillRect(0, 0, canvas.clientWidth, canvas.clientHeight);
+            c.fillStyle = "#7f829c";
+            c.font = "12px ui-monospace, monospace";
+            c.textAlign = "center";
+            c.fillText("no audio", canvas.clientWidth / 2, canvas.clientHeight / 2);
+          }
+        });
+      return;
+    }
+
+    // Nothing to draw.
+    const c = canvas.getContext("2d");
+    if (c) {
+      c.fillStyle = "#12131b";
+      c.fillRect(0, 0, canvas.clientWidth, canvas.clientHeight);
+    }
+  }, [midiBytes, audioUrl]);
+
+  return (
+    <div className="w-full">
+      {label && (
+        <div className="mb-1 font-mono text-[10px] uppercase tracking-widest text-[#7f829c]">
+          {label}
+        </div>
+      )}
+      <canvas
+        ref={canvasRef}
+        className="w-full rounded border border-[#2a2d3d] bg-[#12131b]"
+        style={{ height }}
+      />
+    </div>
+  );
+}

apps/web/lib/midi/generator.ts

@@ -0,0 +1,106 @@
+/**
+ * MIDI file generator.
+ *
+ * Wraps @tonejs/midi to convert MidiEvent[] into a Uint8Array (.mid file bytes)
+ * suitable for download or for the drag-and-drop-into-Reaper flow.
+ *
+ * Source: docs/03-data-model.md §MIDI generation.
+ */
+
+import { Midi } from "@tonejs/midi";
+import {
+  LIMB_TO_GM,
+  type Limb,
+  type MidiEvent,
+} from "@patterntalk/shared-types";
+import { bpmToMicrosecondsPerQuarter } from "../patterns/engine";
+
+export interface MidiMeta {
+  patternId: string;
+  patternName: string;
+  bars: number;
+  bpm: number;
+}
+
+/**
+ * Convert MidiEvent[] to a SMF (Standard MIDI File) byte buffer.
+ * One track, channel 10 (the GM drum channel).
+ */
+export function eventsToMidi(events: MidiEvent[], meta: MidiMeta): Uint8Array {
+  const midi = new Midi();
+
+  // Tempo + time signature on the master track header.
+  midi.header.setTempo(bpmToMicrosecondsPerQuarter(meta.bpm));
+  midi.header.timeSignatures = [{ ticks: 0, timeSignature: [4, 4] }];
+
+  const drums = midi.addTrack();
+  drums.name = `${meta.patternName} (Jam Buddy)`;
+  drums.channel = 9; // 0-indexed; SMF channel 10 is the GM drum channel.
+
+  for (const ev of events) {
+    const midiNote = LIMB_TO_GM[ev.limb];
+    drums.addNote({
+      midi: midiNote,
+      ticks: ev.tick,
+      durationTicks: ev.duration,
+      velocity: ev.velocity / 127,
+    });
+  }
+
+  return midi.toArray();
+}
+
+/**
+ * Build a filename per docs/07-reaper-integration.md §File naming.
+ * Example: jambuddy-d-beat-4bars-180bpm-2026-08-22T1430Z.mid
+ */
+export function midiFilename(meta: MidiMeta, when: Date = new Date()): string {
+  const ts = when.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+  return `jambuddy-${meta.patternId}-${meta.bars}bars-${meta.bpm}bpm-${ts}.mid`;
+}
+
+/**
+ * Trigger a browser download of the MIDI file. Returns the filename used.
+ *
+ * The caller is responsible for the Reaper drag-and-drop UX (see
+ * docs/07-reaper-integration.md §Drag-from-browser directly into Reaper)
+ * — this is the simpler click-to-download path, kept as the reliable fallback.
+ */
+export function downloadMidi(events: MidiEvent[], meta: MidiMeta): string {
+  const bytes = eventsToMidi(events, meta);
+  // `new Uint8Array(...)` re-wraps as a plain (non-SharedArrayBuffer-backed)
+  // ArrayBuffer — required by lib.dom.d.ts in TS 5.7+.
+  const blob = new Blob([new Uint8Array(bytes)], { type: "audio/midi" });
+  const url = URL.createObjectURL(blob);
+  const filename = midiFilename(meta);
+
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.rel = "noopener";
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+
+  // Revoke after a tick so the download has time to start.
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+
+  return filename;
+}
+
+/**
+ * Inverse of downloadMidi: build a File object suitable for the HTML5
+ * drag-and-drop API (DataTransfer.files). Used for drag-from-browser
+ * directly into a Reaper track.
+ */
+export function midiAsFile(events: MidiEvent[], meta: MidiMeta): File {
+  const bytes = eventsToMidi(events, meta);
+  return new File(
+    [new Uint8Array(bytes)],
+    midiFilename(meta),
+    { type: "audio/midi" },
+  );
+}
+
+// Re-export Limb for convenience — keeps consumers from digging into shared-types.
+export type { Limb };

apps/web/lib/patterns/engine.ts

@@ -0,0 +1,273 @@
+/**
+ * Pattern engine.
+ *
+ * Expands a PatternTemplate into MidiEvent[] given the user's request.
+ * Pure function — no DOM, no audio, no I/O. Test this thoroughly.
+ *
+ * Process (per docs/03-data-model.md §Pattern engine):
+ *   1. Load template
+ *   2. Expand to requested bars (repeat template.defaultBars pattern N times)
+ *   3. Apply cymbal override (replace ride/hihat hits with cymbal type)
+ *   4. Apply accents (+20 velocity on matching positions)
+ *   5. Apply feel modifier (swing / half-time / double-time)
+ *   6. Convert fractional positions (0.0–1.0) to absolute ticks at tempoBpm
+ */
+
+import type {
+  Hit,
+  Limb,
+  MidiEvent,
+  ParsedRequest,
+  PatternTemplate,
+} from "@patterntalk/shared-types";
+
+/** MIDI ticks per quarter note. The de facto standard (also SMTE/QT). */
+export const TICKS_PER_QUARTER = 480;
+
+/** Compute ticks-per-bar for a given time signature. */
+export function ticksPerBar(
+  timeSignature: { numerator: number; denominator: number },
+): number {
+  // A bar = numerator quarter notes, regardless of denominator.
+  return TICKS_PER_QUARTER * timeSignature.numerator;
+}
+
+export interface EngineOverrides {
+  cymbal?: ParsedRequest["cymbal"];
+  accents?: string[];
+  feel?: ParsedRequest["feel"];
+}
+
+export interface EngineInput {
+  template: PatternTemplate;
+  bars: number;
+  bpm: number;
+  timeSignature?: { numerator: number; denominator: number };
+  overrides?: EngineOverrides;
+}
+
+/** Limb set considered "cymbal-shaped" — replaced by a cymbal override. */
+const CYMBAL_LIMBS: ReadonlySet<Limb> = new Set([
+  "hihat",
+  "hihat-open",
+  "ride",
+  "ride-bell",
+  "crash",
+  "china",
+  "splash",
+]);
+
+/** Map cymbal hint to a Limb. */
+function cymbalToLimb(type: NonNullable<ParsedRequest["cymbal"]>["type"]): Limb {
+  switch (type) {
+    case "crash":
+      return "crash";
+    case "ride":
+      return "ride-bell"; // default ride → ride-bell (8ths on the bell)
+    case "china":
+      return "china";
+    case "hihat-open":
+      return "hihat-open";
+    case "hihat-closed":
+      return "hihat";
+    case "splash":
+      return "splash";
+  }
+}
+
+interface ExpandedBar {
+  /** 0-based bar index. */
+  barIndex: number;
+  hits: Array<{ hit: Hit; tick: number }>;
+}
+
+/**
+ * Expand a template to N bars. Repeats the template's `defaultBars` pattern
+ * until N bars are filled. Velocity humanization: tiny per-bar nudge so
+ * repeated bars don't sound robotic.
+ */
+function expandBars(input: EngineInput): ExpandedBar[] {
+  const ts = input.timeSignature ?? { numerator: 4, denominator: 4 };
+  const barTicks = ticksPerBar(ts);
+  const template = input.template;
+  const repeatLength = Math.max(1, template.defaultBars);
+  const totalBars = Math.max(1, Math.floor(input.bars));
+
+  const result: ExpandedBar[] = [];
+  for (let barIndex = 0; barIndex < totalBars; barIndex++) {
+    // Index into the template pattern (handles templates that cover > 1 bar)
+    const templateBarIndex = barIndex % repeatLength;
+
+    // Humanization: ±2 velocity, deterministic per bar index.
+    const humanize = (barIndex * 17 + 11) % 5 - 2;
+
+    const hits: Array<{ hit: Hit; tick: number }> = [];
+    for (const hit of template.hits) {
+      // Filter hits to only those in the current template bar.
+      // Hits can have positions across multiple bars; we only want the ones
+      // for the current templateBarIndex. Since positions are 0.0–1.0 within
+      // a single bar, all hits in a single-bar template belong to bar 0;
+      // for multi-bar templates the position encoding is per-bar.
+      if (template.defaultBars === 1 || templateBarIndex === 0) {
+        // Clamp position to [0, 1) — guards against authoring errors.
+        const pos = Math.max(0, Math.min(0.999_999, hit.position));
+        const tick = Math.round(barIndex * barTicks + pos * barTicks);
+        const velocity = Math.max(
+          1,
+          Math.min(127, hit.velocity + humanize),
+        );
+        hits.push({ hit: { ...hit, velocity }, tick });
+      }
+    }
+    result.push({ barIndex, hits });
+  }
+  return result;
+}
+
+/**
+ * Apply a cymbal override. For each expanded hit whose limb is a cymbal,
+ * replace the limb with the override's target.
+ *
+ * For multi-bar templates we only override cymbals in the bars that exist.
+ */
+function applyCymbalOverride(
+  bars: ExpandedBar[],
+  cymbal: NonNullable<ParsedRequest["cymbal"]>,
+): ExpandedBar[] {
+  const target: Limb = cymbalToLimb(cymbal.type);
+  return bars.map((bar) => ({
+    ...bar,
+    hits: bar.hits.map(({ hit, tick }) =>
+      CYMBAL_LIMBS.has(hit.limb)
+        ? { hit: { ...hit, limb: target }, tick }
+        : { hit, tick },
+    ),
+  }));
+}
+
+/**
+ * Apply accent boosts. For each accent descriptor, find hits whose position
+ * matches and boost velocity by +20.
+ *
+ * GOTCHA: `barTicks` must come from `ticksPerBar(timeSignature)`, NOT from
+ * any property of `bars[N]`. `ExpandedBar` has `{ barIndex, hits }` — no
+ * `.tick` field. Reading `bars[1]?.tick` returns undefined, which silently
+ * collapses `barTicks` to 1, and accents then only match bar 0. Regression
+ * test: "__tests__/engine.test.ts > regression: accents apply to ALL bars".
+ *
+ * Supported descriptors (start of v1):
+ *   "1", "2", "3", "4"        — beats within a 4/4 bar
+ *   "and-of-2", "and-of-4"    — classic backbeat accents
+ */
+function applyAccents(
+  bars: ExpandedBar[],
+  accents: string[],
+  timeSignature: { numerator: number; denominator: number } = { numerator: 4, denominator: 4 },
+): ExpandedBar[] {
+  const barTicks = ticksPerBar(timeSignature);
+  const quarter = TICKS_PER_QUARTER;
+
+  return bars.map((bar) => {
+    const hits = bar.hits.map(({ hit, tick }) => {
+      const localTick = tick - bar.barIndex * barTicks;
+      // Position within the bar in quarter notes
+      const localQuarter = localTick / quarter;
+      const beat = Math.floor(localQuarter) + 1; // 1-based
+      const isAnd = (localQuarter - Math.floor(localQuarter)) > 0.4;
+      const localPos = `${beat}${isAnd ? "-and" : ""}`;
+
+      const matched = accents.some((a) => {
+        if (a === localPos) return true;
+        if (a === "1" && beat === 1 && !isAnd) return true;
+        if (a === "3" && beat === 3 && !isAnd) return true;
+        if (a === "and-of-2" && beat === 2 && isAnd) return true;
+        if (a === "and-of-4" && beat === 4 && isAnd) return true;
+        return false;
+      });
+
+      return matched
+        ? {
+            hit: { ...hit, velocity: Math.min(127, hit.velocity + 20), accent: true },
+            tick,
+          }
+        : { hit, tick };
+    });
+    return { ...bar, hits };
+  });
+}
+
+/**
+ * Apply feel modifier. v1 supports swing (delays offbeat 8ths by swingRatio).
+ * Half-time and double-time are recognized but not yet implemented —
+ * TODO for the engine-extension PR.
+ */
+function applyFeel(
+  bars: ExpandedBar[],
+  feel: NonNullable<ParsedRequest["feel"]>,
+  swingRatio: number,
+  timeSignature: { numerator: number; denominator: number } = { numerator: 4, denominator: 4 },
+): ExpandedBar[] {
+  if (feel !== "swing") return bars; // half-time / double-time deferred
+
+  const barTicks = ticksPerBar(timeSignature);
+  const quarter = TICKS_PER_QUARTER;
+  const swingOffset = Math.round(swingRatio * quarter);
+
+  return bars.map((bar) => ({
+    ...bar,
+    hits: bar.hits.map(({ hit, tick }) => {
+      const localTick = tick - bar.barIndex * barTicks;
+      const localQuarter = localTick / quarter;
+      const isAnd = (localQuarter - Math.floor(localQuarter)) > 0.4;
+      return isAnd
+        ? { hit, tick: tick + swingOffset }
+        : { hit, tick };
+    }),
+  }));
+}
+
+/**
+ * Expand a PatternTemplate into MidiEvent[] for the requested bars and tempo.
+ *
+ * This is the single entry point used by the MIDI generator and by tests.
+ */
+export function expandPattern(input: EngineInput): MidiEvent[] {
+  const ts = input.timeSignature ?? { numerator: 4, denominator: 4 };
+  const overrides = input.overrides ?? {};
+
+  let bars = expandBars(input);
+
+  if (overrides.cymbal) {
+    bars = applyCymbalOverride(bars, overrides.cymbal);
+  }
+  if (overrides.accents && overrides.accents.length > 0) {
+    bars = applyAccents(bars, overrides.accents, ts);
+  }
+  if (overrides.feel) {
+    bars = applyFeel(bars, overrides.feel, input.template.swingRatio ?? 0, ts);
+  }
+
+  const events: MidiEvent[] = [];
+  for (const bar of bars) {
+    for (const { hit, tick } of bar.hits) {
+      events.push({
+        tick,
+        limb: hit.limb,
+        velocity: hit.velocity,
+        duration: 8, // ~8 ticks — short drum hit
+      });
+    }
+  }
+
+  // Sort by tick for clean MIDI output.
+  events.sort((a, b) => a.tick - b.tick);
+  return events;
+}
+
+/**
+ * Compute the bar-tempo in microseconds-per-quarter-note for the MIDI header.
+ * Standard MIDI tempo meta-event.
+ */
+export function bpmToMicrosecondsPerQuarter(bpm: number): number {
+  return Math.round(60_000_000 / bpm);
+}

apps/web/lib/voice/conversation.ts

@@ -0,0 +1,219 @@
+/**
+ * Voice conversation state machine.
+ *
+ * The single source of truth for "what state is the voice UI in."
+ * Consumed by the React layer to decide which UI is shown and which
+ * speech synthesis phrase to play.
+ *
+ * States (docs/04-ux-voice-first.md + two additions for error handling
+ * and confirmation):
+ *
+ *   idle                      — nothing happening
+ *   listening                 — mic active, capturing
+ *   parsing                   — got final transcript, running the parser
+ *   awaiting-confirmation     — parser confidence < 0.7, user must pick
+ *   generating                — pattern engine + audio service running
+ *   ready                     — MIDI + sample available, awaiting next command
+ *   playing                   — audio preview playing
+ *   error                     — recoverable failure (mic denied, parse error)
+ *
+ * Transitions are encoded as a pure function — given (state, event) return
+ * (nextState, side-effects). The React layer (or a test) executes side-effects.
+ */
+
+import type {
+  ConversationContext,
+  ConversationState,
+  ParseResult,
+} from "@patterntalk/shared-types";
+
+/** Events that drive state transitions. */
+export type ConversationEvent =
+  | { type: "START_LISTENING" }
+  | { type: "STOP_LISTENING" }
+  | { type: "TRANSCRIPT_FINAL"; transcript: string }
+  | { type: "PARSE_OK"; result: Extract<ParseResult, { ok: true }> }
+  | { type: "PARSE_LOW_CONFIDENCE"; result: Extract<ParseResult, { ok: false }> }
+  | { type: "CONFIRM_CANDIDATE"; index: number }
+  | { type: "GENERATION_OK"; sampleUrl?: string; variations?: number }
+  | { type: "GENERATION_FAIL"; message: string }
+  | { type: "PLAY_START" }
+  | { type: "PLAY_STOP" }
+  | { type: "RESET" }
+  | { type: "ERROR"; kind: NonNullable<ConversationContext["error"]>["kind"]; message: string };
+
+export interface Transition {
+  next: ConversationState;
+  context: ConversationContext;
+  /** Side effects the host should run (TTS, API calls, etc.). */
+  sideEffects: ConversationSideEffect[];
+}
+
+export type ConversationSideEffect =
+  | { type: "SPEAK"; text: string; interrupt: boolean }
+  | { type: "START_MIC" }
+  | { type: "STOP_MIC" }
+  | { type: "TRIGGER_GENERATION" }
+  | { type: "TRIGGER_PLAYBACK" }
+  | { type: "TRIGGER_STOP" };
+
+/**
+ * Pure transition function. Given a state + event, returns the next state,
+ * updated context, and side-effects to run.
+ *
+ * Unknown events for the current state are ignored (returns same state).
+ * This is intentional — voice UIs receive many stray events; the FSM
+ * should be quiet when not in the right state.
+ */
+export function transition(
+  state: ConversationState,
+  context: ConversationContext,
+  event: ConversationEvent,
+): Transition {
+  switch (event.type) {
+    case "RESET":
+      return {
+        next: "idle",
+        context: {},
+        sideEffects: [{ type: "SPEAK", text: "Starting over.", interrupt: true }],
+      };
+
+    case "START_LISTENING": {
+      if (state !== "idle" && state !== "ready" && state !== "error") {
+        return { next: state, context, sideEffects: [] };
+      }
+      return {
+        next: "listening",
+        context: {},
+        sideEffects: [{ type: "START_MIC" }],
+      };
+    }
+
+    case "STOP_LISTENING": {
+      if (state !== "listening") {
+        return { next: state, context, sideEffects: [] };
+      }
+      return {
+        next: state,
+        context,
+        sideEffects: [{ type: "STOP_MIC" }],
+      };
+    }
+
+    case "TRANSCRIPT_FINAL": {
+      if (state !== "listening") {
+        return { next: state, context, sideEffects: [] };
+      }
+      return {
+        next: "parsing",
+        context: {},
+        sideEffects: [
+          { type: "STOP_MIC" },
+          { type: "SPEAK", text: "Parsing.", interrupt: false },
+        ],
+      };
+    }
+
+    case "PARSE_OK": {
+      if (state !== "parsing") return { next: state, context, sideEffects: [] };
+      return {
+        next: "generating",
+        context: { parsed: event.result.request },
+        sideEffects: [
+          {
+            type: "SPEAK",
+            text: `Generating ${event.result.request.patternName ?? event.result.request.patternId ?? "pattern"}, ${event.result.request.bars} bars at ${event.result.request.tempo ?? event.result.request.tempoDefault} BPM.`,
+            interrupt: true,
+          },
+          { type: "TRIGGER_GENERATION" },
+        ],
+      };
+    }
+
+    case "PARSE_LOW_CONFIDENCE": {
+      if (state !== "parsing") return { next: state, context, sideEffects: [] };
+      const top = event.result.candidates[0];
+      const message = top
+        ? `I heard ${event.result.heardAs}. Did you mean ${top.request.patternName ?? top.request.patternId}?`
+        : `I heard ${event.result.heardAs}, but I'm not sure.`;
+      return {
+        next: "awaiting-confirmation",
+        context: {},
+        sideEffects: [{ type: "SPEAK", text: message, interrupt: true }],
+      };
+    }
+
+    case "CONFIRM_CANDIDATE": {
+      if (state !== "awaiting-confirmation") {
+        return { next: state, context, sideEffects: [] };
+      }
+      // The host should have stored the candidates in context.candidates.
+      // We can't store ParseResult directly because it lives in shared-types;
+      // for now, callers pass the index and the host resolves it externally.
+      // This is intentional — keeps the FSM serializable.
+      return {
+        next: "generating",
+        context,
+        sideEffects: [{ type: "TRIGGER_GENERATION" }],
+      };
+    }
+
+    case "GENERATION_OK": {
+      if (state !== "generating") {
+        return { next: state, context, sideEffects: [] };
+      }
+      return {
+        next: "ready",
+        context: {
+          ...context,
+          sampleUrl: event.sampleUrl,
+          variations: context.variations ?? [],
+        },
+        sideEffects: [
+          {
+            type: "SPEAK",
+            text: "Ready. Say play to preview, regenerate, download MIDI, or new pattern.",
+            interrupt: true,
+          },
+        ],
+      };
+    }
+
+    case "GENERATION_FAIL": {
+      return {
+        next: "error",
+        context: {
+          ...context,
+          error: { kind: "audio-error", message: event.message },
+        },
+        sideEffects: [{ type: "SPEAK", text: event.message, interrupt: true }],
+      };
+    }
+
+    case "PLAY_START": {
+      if (state !== "ready") return { next: state, context, sideEffects: [] };
+      return {
+        next: "playing",
+        context,
+        sideEffects: [{ type: "TRIGGER_PLAYBACK" }],
+      };
+    }
+
+    case "PLAY_STOP": {
+      if (state !== "playing") return { next: state, context, sideEffects: [] };
+      return {
+        next: "ready",
+        context,
+        sideEffects: [{ type: "TRIGGER_STOP" }],
+      };
+    }
+
+    case "ERROR": {
+      return {
+        next: "error",
+        context: { ...context, error: { kind: event.kind, message: event.message } },
+        sideEffects: [{ type: "SPEAK", text: event.message, interrupt: true }],
+      };
+    }
+  }
+}

apps/web/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.

apps/web/next.config.mjs

@@ -0,0 +1,16 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  // PatternTalk's audio service runs on a different port (8001); in dev we
+  // proxy /api/audio/* there to avoid CORS. See feat/audio-service PR.
+  async rewrites() {
+    return [
+      {
+        source: "/api/audio/:path*",
+        destination: "http://localhost:8001/:path*",
+      },
+    ];
+  },
+};
+
+export default nextConfig;

apps/web/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@patterntalk/web",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev -p 3000",
+    "build": "next build",
+    "start": "next start -p 3000",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@patterntalk/shared-types": "workspace:*",
+    "@tonejs/midi": "^2.0.28",
+    "next": "^14.2.18",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.3",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.20",
+    "eslint": "^8.57.1",
+    "eslint-config-next": "^14.2.18",
+    "happy-dom": "^15.11.7",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.15",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}

apps/web/postcss.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

apps/web/scripts/_debug_jambuddy.cjs

@@ -0,0 +1,28 @@
+const { execFile } = require("node:child_process");
+const { promisify } = require("node:util");
+const execFileAsync = promisify(execFile);
+const { join } = require("node:path");
+
+const repoRoot = join(__dirname, "..", "..", "..");
+const python = join(repoRoot, "stable-audio-3", ".venv", "Scripts", "python.exe");
+const script = join(repoRoot, "tools", "jam_buddy.py");
+const out = join(require("node:os").tmpdir(), "out.wav");
+
+execFileAsync(
+  python,
+  [script, "--bpm", "120", "--out", out],
+  { timeout: 300000, maxBuffer: 10 * 1024 * 1024 },
+)
+  .then(({ stdout }) => {
+    console.log("OK. stdout bytes:", stdout.length);
+    console.log("tail:", stdout.slice(-200));
+  })
+  .catch((err) => {
+    console.log("ERROR name:", err.name);
+    console.log("ERROR code:", err.code);
+    console.log("ERROR killed:", err.killed);
+    console.log("ERROR signal:", err.signal);
+    console.log("ERROR message:", err.message);
+    console.log("ERROR stderr:", JSON.stringify(err.stderr));
+    console.log("ERROR stdout:", JSON.stringify(err.stdout?.slice(-300)));
+  });

apps/web/tailwind.config.ts

@@ -0,0 +1,29 @@
+import type { Config } from "tailwindcss";
+
+const config: Config = {
+  content: [
+    "./app/**/*.{ts,tsx}",
+    "./components/**/*.{ts,tsx}",
+    "./lib/**/*.{ts,tsx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        // Per docs/05-accessibility.md §High contrast and theming
+        bg: "var(--bg)",
+        fg: "var(--fg)",
+        accent: "var(--accent)",
+        focus: "var(--focus)",
+        "limb-kick": "var(--limb-kick)",
+        "limb-snare": "var(--limb-snare)",
+        "limb-hihat": "var(--limb-hihat)",
+        "limb-ride": "var(--limb-ride)",
+        "limb-crash": "var(--limb-crash)",
+        "limb-china": "var(--limb-china)",
+      },
+    },
+  },
+  plugins: [],
+};
+
+export default config;

apps/web/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "preserve",
+    "allowJs": false,
+    "noEmit": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": ["node_modules", ".next", "dist", "__tests__/**/*"]
+}

apps/web/vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+import path from "node:path";
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: "happy-dom",
+    globals: false,
+    include: ["__tests__/**/*.test.ts", "__tests__/**/*.test.tsx"],
+  },
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "."),
+    },
+  },
+});

docs/01-vision.md

@@ -0,0 +1,90 @@
+# 01 — Vision
+
+## The problem
+
+Music generators and practice tools don't act like a bandmate. You sit down,
+start playing, and the software asks you to describe what you want in its terms
+— or it produces a finished "song" you have no part in. There's no tool that
+just **listens to what you're playing and joins in**.
+
+AI music tools compound the problem:
+- They generate full mixes at a fixed tempo, not parts that lock to *your* tempo.
+- They're visual toy apps or opaque audio generators with no semantic structure,
+  so blind and visually impaired producers can't use them at all.
+
+## The product
+
+**Jam Buddy** is a call-and-response practice companion. The interaction is the
+product: *you start playing, it joins in at your tempo, in the instrument you
+pick.*
+
+1. You load a **MIDI take** (controller) or **audio take** (mic/interface).
+2. The buddy detects your tempo (exact from MIDI note times; tempo-range prior
+   on audio) and matches its response length to your take.
+3. You pick the **instrument** the buddy should play (bass / lead / rhythm /
+   synth / drums) plus a genre and mood.
+4. SA3 generates the response — `small-music` for melodic parts, `small-sfx`
+   for clean isolated drums — at your tempo.
+5. **PLAY BOTH** plays your take and the buddy's response together, in tempo.
+6. Every response is saved to `generations/` so you can keep and A/B it.
+
+The UI is a hardware-sampler-styled rack, and it's **screenreader-compatible by
+design**: labelled range-input knobs, accessible button names, `aria-live`
+status. Voice-first *is* accessibility — we build the accessible version first,
+not as an afterthought.
+
+## Why this fits the Stability AI challenge
+
+The brief asks for *"a publicly available and accessible tool for music
+producers using the power of the Stable Audio 3 models, encouraging open
+development and showing the strengths of local open models."*
+
+- **SA3 powers the response** — generated locally from the open `small-music` /
+  `small-sfx` weights, no black-box API.
+- **Two real input modes**: MIDI (tempo + length lock) and audio
+  (audio-to-audio — the buddy genuinely hears and responds to your groove).
+- **Accessibility as load-bearing**, not bolted on.
+- **Open + local**: the whole pipeline runs on consumer hardware.
+
+## Who this is for
+
+**Primary:**
+- Musicians who want a practice partner that locks to *their* tempo.
+- Producers exploring complementary parts without leaving their flow.
+- Blind / visually impaired producers — the rack is fully keyboard + screenreader
+  operable.
+
+**Secondary:**
+- Any jam context — one player's take, a generated counterpart in the room.
+
+## What success looks like at the hackathon
+
+**Demo (3–4 minutes):**
+1. Elevator pitch: *"a practice partner that hears you start playing and joins
+   in at your tempo, in your instrument."*
+2. Load a MIDI take from a real controller.
+3. Pick an instrument, hit JOIN IN — the buddy responds at your tempo.
+4. PLAY BOTH — you + the buddy together, the co-play moment.
+5. Toggle the keyboard/screenreader path to show accessibility.
+6. Point at the `generations/` files — everything it produced is kept.
+
+**Deliverables:**
+- Working web app (`apps/web`) + the `tools/jam_buddy.py` SA3 pipeline.
+- Open-source MIT repo.
+- Screenreader-tested UI (NVDA + VoiceOver).
+
+**Stretch / not claimed:**
+- A LoRA fine-tune for "your style" is a real path (via `underfit` on a GPU)
+  but is NOT shipped — we demo the open local model, honestly.
+
+## What we explicitly are not
+
+- Not a DAW. Reaper / the DAW does that.
+- Not a full song generator. We produce one complementary part at your tempo.
+- Not a VST first. The web rack is the primary surface; plugin wrap is stretch.
+
+## North star
+
+A musician plays a 20-second idea, picks "lead guitar," and within a minute the
+buddy has responded with a lead part at the same tempo — and both play together.
+That's the co-play moment we're building toward.

docs/02-architecture.md

@@ -0,0 +1,271 @@
+# 02 — Architecture
+
+## System overview
+
+PatternTalk is two services plus a shared data layer.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        Browser                              │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  Next.js Web App (TypeScript)                        │   │
+│  │  ├─ Voice UI (Web Speech API: STT + TTS)            │   │
+│  │  ├─ Prompt parser                                   │   │
+│  │  ├─ Pattern engine (loads templates)                │   │
+│  │  ├─ MIDI generator (@tonejs/midi)                   │   │
+│  │  ├─ Audio context analyzer (Meyda/Essentia.js)      │   │
+│  │  ├─ Reaper Web Control client                       │   │
+│  │  └─ Visual grid (optional, layered on top)          │   │
+│  └──────────────────────────────────────────────────────┘   │
+└──────────┬──────────────────────────────────┬───────────────┘
+           │ HTTP                              │ WebSocket
+           ▼                                  ▼
+┌──────────────────────┐          ┌────────────────────────────┐
+│  Audio Service       │          │  Reaper (user's machine)   │
+│  (Python, FastAPI)   │          │  Web Control surface       │
+│  ├─ SA3 inference    │          │  + ReaScript bridge        │
+│  ├─ LoRA loader      │          └────────────────────────────┘
+│  └─ Sample generator │
+└──────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────┐
+│  Stable Audio 3 weights (local FS)   │
+│  + Brutal-drum LoRA adapter          │
+└──────────────────────────────────────┘
+```
+
+## Services
+
+### 1. Web app (`apps/web`)
+
+**Stack:** Next.js 14+ (App Router), TypeScript, Tailwind CSS, Radix UI primitives, @tonejs/midi, Meyda.
+
+**Responsibilities:**
+- Render the voice-first UI
+- Capture microphone input → text via Web Speech API (`SpeechRecognition`)
+- Speak responses via `SpeechSynthesis`
+- Parse prompts → structured requests (see [`docs/03-data-model.md`](03-data-model.md))
+- Load pattern templates, generate MIDI in-browser
+- Optional: analyze uploaded audio for BPM (Meyda/Essentia.js)
+- Talk to Reaper via Web Control (when available)
+- Talk to audio service for sample generation
+
+**State management:** Zustand or React state. Avoid Redux. State is small.
+
+**Why Next.js:**
+- Server components let us split render work from interactive shell
+- Easy deploy to Vercel
+- TS support is first-class
+- Accessibility ecosystem (react-aria, Radix) is mature
+
+### 2. Audio service (`services/audio`)
+
+**Stack:** Python 3.10+, FastAPI, PyTorch 2.x, diffusers/transformers for SA3.
+
+**Responsibilities:**
+- Load Stable Audio 3 weights (base model)
+- Load LoRA adapter (brutal-drums)
+- Run inference on prompts → audio buffers
+- Stream or return audio as WAV
+- Cache generated samples (LRU + disk-backed)
+
+**Why separate service:**
+- Python ML ecosystem is non-negotiable for SA3
+- Decoupling lets us run on different machines (Vega for dev, cloud GPU for demo)
+- Browser can't run SA3 inference efficiently
+- Service can be scaled or replaced without touching the web app
+
+### 3. Reaper integration (in user's DAW)
+
+**Stack:** Reaper Web Control surface (built-in HTTP server) + optional ReaScript.
+
+**Responsibilities:**
+- Expose project tempo (BPM), time signature, play state
+- Accept MIDI files dropped onto tracks
+
+**Why this is not a "service":**
+- Reaper runs on the user's machine
+- PatternTalk is a client to its Web Control API
+- No persistent server-side integration needed
+
+## Data flow
+
+### Happy path: voice prompt → MIDI + sample
+
+```
+User voice: "tupatupatupa on the hihat, 4 bars"
+    │
+    ▼
+[Web Speech API] ──text──▶ "tupatupatupa on the hihat, 4 bars"
+    │
+    ▼
+[Onomatopoeia matcher] ──▶ { onomatopoeia: "tupatupatupa", mappedTo: "skank-beat" }
+    │
+    ▼
+[Prompt parser] ──▶ {
+    │                   pattern: "skank-beat",
+    │                   bars: 4,
+    │                   tempo: null,           // not specified
+    │                   timeSignature: "4/4",  // default
+    │                   cymbalHint: "hi-hat upstrokes"
+    │                 }
+    ▼
+[Tempo resolver] ──▶ tempo: 174
+    │  (priority: explicit in prompt > Reaper project BPM > uploaded audio BPM > 120 default)
+    ▼
+[Pattern engine] ──▶ MIDI events[]   (loaded from skank-beat template, expanded to 4 bars at 174 BPM)
+    │
+    ▼
+[MIDI generator] ──▶ .mid file (Blob in browser)
+    │
+    ├─▶ [Download to user]
+    │
+    └─▶ [Audio service request]
+        POST /generate-sample
+        { prompt: "skank beat, hi-hat upstrokes, brutal drums", duration: 8 }
+        │
+        ▼
+        [SA3 + LoRA inference] ──▶ audio buffer
+        │
+        ▼
+        [Response] ──▶ .wav file (Blob in browser)
+        │
+        └─▶ [Download to user]
+```
+
+### Voice response flow
+
+After generation, PatternTalk speaks back:
+
+```
+"Skank beat, hi-hat upstrokes on the upbeats, 4 bars at 174 BPM.
+ MIDI ready. Sample ready. Say 'play' to preview, 'regenerate' to try again,
+ or 'download' to save the MIDI."
+```
+
+### Reaper sync flow
+
+```
+Web app mounts → checks for Reaper Web Control at localhost:8080
+    │
+    ├─ present → fetch /_/project/tempo → use as tempo default
+    │
+    └─ absent → use uploaded audio BPM or 120 default
+```
+
+## Folder structure
+
+```
+patterntalk/
+├── apps/
+│   └── web/                       # Next.js app
+│       ├── app/                   # App Router pages
+│       │   ├── page.tsx           # Main voice UI
+│       │   ├── library/           # Pattern library
+│       │   └── layout.tsx
+│       ├── components/
+│       │   ├── voice/             # Voice UI primitives
+│       │   ├── grid/              # Visual grid (optional)
+│       │   └── ui/                # Radix wrappers
+│       ├── lib/
+│       │   ├── parser/            # Prompt + onomatopoeia parser
+│       │   ├── patterns/          # Pattern engine + template loader
+│       │   ├── midi/              # MIDI generation (@tonejs/midi)
+│       │   ├── audio/             # Web Audio, Meyda analyzer
+│       │   └── reaper/            # Reaper Web Control client
+│       ├── data/
+│       │   ├── patterns/          # JSON pattern templates
+│       │   └── onomatopoeia.json  # Onomatopoeia mapping table
+│       ├── public/
+│       └── package.json
+├── services/
+│   └── audio/                     # FastAPI service
+│       ├── sa3/                   # SA3 wrapper
+│       │   ├── inference.py
+│       │   ├── lora.py
+│       │   └── server.py
+│       ├── training/              # LoRA fine-tuning scripts
+│       │   └── train_lora.py
+│       ├── models/                # SA3 base weights (gitignored)
+│       ├── loras/                 # Trained LoRA adapters
+│       ├── cache/                 # Generated sample cache
+│       └── requirements.txt
+├── data/
+│   └── training/                  # Brutal drum samples for LoRA
+│       ├── oneshots/              # Kick, snare, china, etc.
+│       ├── loops/                 # Short brutal loops
+│       └── manifest.yaml          # Training data manifest
+├── docs/                          # This directory
+├── scripts/
+│   ├── reaper/                    # ReaScript helpers
+│   └── verify/                    # Accessibility + smoke tests
+├── .github/
+│   └── workflows/                 # CI (axe-core, lint, build)
+├── package.json                   # Workspace root
+└── README.md
+```
+
+## Why monorepo
+
+- Single repo for web + audio service + training data
+- Shared types between TS and Python (via JSON Schema + codegen, or just hand-written TS interfaces mirrored in Pydantic)
+- Single CI pipeline
+- Easier to ship as one artifact at the demo
+
+**Tooling:** pnpm workspaces + a simple Python venv per service. Avoid Turborepo/Nx overhead for a 2-day project.
+
+## Deployment
+
+| Component | Target |
+|---|---|
+| Web app | Vercel (free tier) |
+| Audio service | RunPod / Vast.ai during hackathon, optional Fly.io / Modal for inference |
+| Models + LoRA weights | HuggingFace Hub (public, for the LoRA at least) |
+| Training data | Small dataset, commit directly to repo or HuggingFace dataset |
+
+## Key technical decisions
+
+### Decision 1: Voice-first, not visual-first
+
+The voice UI is the primary surface. The visual grid is optional and layered.
+
+**Rationale:** Differentiates from every other drum plugin, hits the accessibility theme head-on, and matches how drummers actually think.
+
+### Decision 2: Pattern engine decoupled from audio engine
+
+The pattern (MIDI events) is hand-coded from templates. The audio (samples) is generated by SA3.
+
+**Rationale:** Your domain expertise lives in the patterns. SA3's strength is sample quality. Don't conflate them. Each can be evaluated independently.
+
+### Decision 3: Cloud GPU for inference during demo
+
+Vega 56 can run SA3 small but slowly. Use cloud for demo-day inference to guarantee snappy response.
+
+**Rationale:** Live inference during a 3-minute demo is high-risk if hardware is slow. A $20 cloud spend buys reliability.
+
+### Decision 4: Open weights and open code
+
+MIT code, public LoRA weights, public training manifest.
+
+**Rationale:** Stability challenge explicitly rewards "open development." Showing the weights and training data is itself part of the demo.
+
+### Decision 5: Reaper-first DAW integration
+
+Web Control surface + MIDI export, not a full VST/CLAP.
+
+**Rationale:** Web Control + drag-MIDI is 80% of the value at 20% of the work. CLAP wrap is stretch.
+
+## What this architecture doesn't do
+
+- No multi-user real-time collaboration (out of scope for 2 days)
+- No pattern saving to cloud accounts (localStorage only for now)
+- No mobile-first UI (desktop browser is the target)
+- No offline mode (Vega inference can run offline, but the demo assumes network for cloud inference)
+- No AU plugin format (Mac pain, not worth it for the demo)
+
+## Open architectural questions
+
+1. **Where does the pattern library live?** Browser-only (static JSON) vs. served from the audio service? *Lean: browser-only, simpler.*
+2. **Should variations be pre-generated or on-demand?** Pre-generated is faster demo, on-demand is more impressive. *Lean: pre-generate for safety, on-demand as a "show your work" feature.*
+3. **Real-time WebSocket for inference progress, or just polling?** WebSocket is nicer UX, polling is simpler. *Lean: WebSocket if time, polling if not.*

docs/03-data-model.md

@@ -0,0 +1,400 @@
+# 03 — Data Model
+
+## Overview
+
+PatternTalk's core data is small and human-editable. Most of it lives in JSON files under `apps/web/data/` and `data/training/`.
+
+```
+Prompt (user voice/text)
+  │
+  ▼
+ParsedRequest  ◄── onomatopoeia.json + prompt grammar
+  │
+  ▼
+Pattern (loaded from patterns/*.json, expanded to bars + tempo)
+  │
+  ▼
+MIDI events
+  │
+  ▼
+.mid file
+```
+
+## Prompt grammar
+
+User input is freeform text, but parses into a structured `ParsedRequest`.
+
+```typescript
+interface ParsedRequest {
+  // Source pattern
+  onomatopoeia?: string;          // e.g. "tupatupatupa"
+  patternId?: string;             // e.g. "d-beat", "blast-traditional"
+  patternName?: string;           // e.g. "D-Beat", user-friendly
+
+  // Length
+  bars: number;                   // default 4
+  beats?: number;                 // override pattern beats per bar
+
+  // Tempo
+  tempo?: number;                 // explicit BPM
+  tempoSource: "prompt" | "reaper" | "audio" | "default";
+  tempoDefault: number;           // 120 if nothing else
+
+  // Time signature
+  timeSignature: {
+    numerator: number;            // default 4
+    denominator: number;          // default 4
+  };
+
+  // Cymbal/voice hints
+  cymbal?: {
+    type: "crash" | "ride" | "china" | "hihat-open" | "hihat-closed" | "splash";
+    pattern?: "8ths" | "quarters" | "bell" | "wash" | "upstrokes";
+  };
+
+  // Accent overrides
+  accents?: ("1" | "and-of-2" | "3" | "and-of-4" | string)[];
+
+  // Style modifiers
+  feel?: "straight" | "swing" | "half-time" | "double-time";
+  intensity?: "soft" | "medium" | "brutal" | "brutal-max";
+}
+```
+
+## Onomatopoeia mapping
+
+`apps/web/data/onomatopoeia.json` is the lookup table the parser checks first.
+
+```json
+{
+  "version": 1,
+  "entries": [
+    {
+      "id": "skank-beat",
+      "patterns": ["tupatupatupa", "tupa-tupa-tupa", "chka-chka-chka"],
+      "patternId": "skank",
+      "defaultCymbal": { "type": "hihat-open", "pattern": "upstrokes" },
+      "confidence": 0.9,
+      "notes": "Ska-style offbeat hi-hat upstrokes."
+    },
+    {
+      "id": "blast-beat",
+      "patterns": ["krrk-krrk-krrk", "BLAM-BLAM-BLAM", "krkrkrkrk"],
+      "patternId": "blast-traditional",
+      "defaultIntensity": "brutal",
+      "confidence": 0.85,
+      "notes": "Traditional blast beat. Kick-snare alternation."
+    },
+    {
+      "id": "boom-bap",
+      "patterns": ["boom-bap", "boom-bap-boom-bap"],
+      "patternId": "hiphop-basic",
+      "confidence": 0.95
+    },
+    {
+      "id": "china-accent",
+      "patterns": ["tss", "chka", "BLAM"],
+      "patternId": "china-accent",
+      "defaultCymbal": { "type": "china", "pattern": "wash" }
+    },
+    {
+      "id": "ride-bell",
+      "patterns": ["ding-ding-ding", "ding-ding-ding-ding"],
+      "patternId": "ride-bell-8ths",
+      "defaultCymbal": { "type": "ride", "pattern": "bell" }
+    }
+  ]
+}
+```
+
+### Matching logic
+
+1. Normalize input: lowercase, strip punctuation, collapse whitespace
+2. Phonetic match: Soundex or simple Levenshtein against entries
+3. Syllable count: "tupatupatupa" = 4 syllables → likely 8th-note hi-hat
+4. Confidence threshold: 0.7 to auto-map, lower to ask user
+
+### User-defined onomatopoeias
+
+Users can add their own mappings via the UI. Stored in `localStorage` per device.
+
+```typescript
+interface UserOnomatopoeia {
+  phrase: string;
+  patternId: string;
+  cymbal?: CymbalHint;
+  createdAt: number;
+}
+```
+
+## Pattern templates
+
+`apps/web/data/patterns/*.json` — one file per pattern. Hand-authored. **This is your moat.**
+
+```typescript
+interface PatternTemplate {
+  id: string;                      // unique slug
+  name: string;                    // "D-Beat"
+  description: string;             // screenreader-friendly text
+  tags: string[];                  // searchable
+  genre: "metal" | "rock" | "punk" | "pop" | "jazz" | "funk" | "latin" | "hiphop";
+  defaultTempo: number;            // BPM
+  defaultBars: number;             // how many bars this template covers
+  swingRatio?: number;             // 0.0 = straight, 0.33 = shuffle
+  hits: Hit[];
+}
+
+interface Hit {
+  position: number;                // 0.0 to 1.0, fraction of one bar
+  limb: Limb;
+  velocity: number;                // 0-127 MIDI velocity
+  accent?: boolean;                // visual + audio emphasis
+}
+
+type Limb =
+  | "kick"           // right foot
+  | "snare"          // left hand (default) or right hand (cross-handed)
+  | "hihat"          // right hand (default) or left hand (cross-handed)
+  | "hihat-open"     // same as hihat but with open hi-hat sample
+  | "ride"
+  | "ride-bell"
+  | "crash"
+  | "china"
+  | "splash"
+  | "tom-1"          // highest
+  | "tom-2"
+  | "tom-3"          // lowest floor tom
+  | "cross-stick";   // rim click
+```
+
+### Example: D-Beat
+
+`apps/web/data/patterns/d-beat.json`:
+
+```json
+{
+  "id": "d-beat",
+  "name": "D-Beat",
+  "description": "D-beat pattern at 180 BPM. Kick plays on every beat with 8th-note doubles, snare hits on 2 and 4, ride bell plays steady 8ths throughout. Common in Discharge, Entombed, and Scandinavian crust punk.",
+  "tags": ["metal", "punk", "discharge", "entombed", "crust", "fast"],
+  "genre": "metal",
+  "defaultTempo": 180,
+  "defaultBars": 1,
+  "swingRatio": 0,
+  "hits": [
+    { "position": 0.0,   "limb": "kick", "velocity": 110 },
+    { "position": 0.125, "limb": "kick", "velocity": 80 },
+    { "position": 0.25,  "limb": "snare", "velocity": 100 },
+    { "position": 0.375, "limb": "kick", "velocity": 80 },
+    { "position": 0.5,   "limb": "kick", "velocity": 110 },
+    { "position": 0.625, "limb": "kick", "velocity": 80 },
+    { "position": 0.75,  "limb": "snare", "velocity": 100 },
+    { "position": 0.875, "limb": "kick", "velocity": 80 },
+    { "position": 0.0,   "limb": "ride-bell", "velocity": 70 },
+    { "position": 0.125, "limb": "ride-bell", "velocity": 70 },
+    { "position": 0.25,  "limb": "ride-bell", "velocity": 70 },
+    { "position": 0.375, "limb": "ride-bell", "velocity": 70 },
+    { "position": 0.5,   "limb": "ride-bell", "velocity": 70 },
+    { "position": 0.625, "limb": "ride-bell", "velocity": 70 },
+    { "position": 0.75,  "limb": "ride-bell", "velocity": 70 },
+    { "position": 0.875, "limb": "ride-bell", "velocity": 70 }
+  ]
+}
+```
+
+### Pattern library — starting list
+
+**Metal (priority, 8 patterns):**
+- `d-beat.json` — D-beat
+- `blast-traditional.json` — traditional blast (kick-snare)
+- `blast-hammer.json` — hammer-and-tongs blast
+- `blast-hyper.json` — hyperblast (double kick 16ths)
+- `half-time-metal.json` — Mastodon/Baroness half-time
+- `djent-polyrhythm.json` — Meshuggah-style 4-over-3 kick
+- `doom-slow.json` — Sleep/Electric Wizard doom
+- `groove-metal.json` — mid-tempo groove metal
+
+**Punk/Hardcore (4 patterns):**
+- `punk-rock.json` — Ramones/Misfits 4-on-floor
+- `hardcore.json` — Black Flag/Converge
+- `skank.json` — ska skank beat (hi-hat upstrokes)
+- `reggae-one-drop.json` — reggae
+
+**Rock/Pop (4 patterns):**
+- `rock-basic.json` — AC/DC/Beatles standard rock
+- `rock-half-time.json` — half-time shuffle
+- `pop-groove.json` — modern pop
+- `country-train.json` — train beat
+
+**Other genres (4 patterns):**
+- `bossa-nova.json` — bossa nova
+- `jazz-swing.json` — jazz ride swing
+- `funk-new-orleans.json` — NOLA funk
+- `hiphop-basic.json` — boom-bap
+
+**Target: 18–20 patterns before hackathon, more as time permits.**
+
+## Pattern engine
+
+Lives in `apps/web/lib/patterns/engine.ts`.
+
+### Inputs
+- `PatternTemplate`
+- `bars: number`
+- `tempoBpm: number`
+- `timeSignature: { numerator, denominator }`
+- Optional `cymbal` override (replaces the default cymbal)
+- Optional `accents` (boosts velocity on specified positions)
+- Optional `feel` modifier
+
+### Process
+
+```
+1. Load template
+2. Expand to requested bars:
+   - If template.defaultBars === requested bars: use as-is
+   - Else: repeat the pattern N times, optionally vary velocity (humanize)
+3. Apply cymbal override:
+   - If cymbal specified: replace ride/hihat hits with cymbal type
+   - Velocity scaled: cymbal typically quieter than snare
+4. Apply accents:
+   - Find positions matching accent specs
+   - Boost velocity by +20
+5. Apply feel modifier:
+   - "swing": delay 8th notes on the "and" by swingRatio
+   - "half-time": halve the effective tempo of snare/hihat
+   - "double-time": double it
+6. Convert positions (0.0-1.0) to absolute ticks at tempoBpm
+7. Return array of MIDI events
+```
+
+### Output
+
+```typescript
+interface MidiEvent {
+  tick: number;                    // absolute tick position
+  limb: Limb;
+  velocity: number;                // 0-127
+  duration: number;                // ticks (typically 1-10 for drums)
+}
+```
+
+## MIDI generation
+
+`apps/web/lib/midi/generator.ts` uses `@tonejs/midi`.
+
+```typescript
+import { Midi } from "@tonejs/midi";
+
+function eventsToMidi(events: MidiEvent[]): Uint8Array {
+  const midi = new Midi();
+  midi.header.setTempo(events.bpm);   // bpm on master track
+  midi.header.timeSignature = [4, 4];
+
+  const drums = midi.addTrack();
+  drums.name = "PatternTalk Drums";
+
+  for (const ev of events) {
+    drums.addNote({
+      midi: limbToGeneralMidi(ev.limb),
+      ticks: ev.tick,
+      durationTicks: ev.duration,
+      velocity: ev.velocity / 127,
+    });
+  }
+
+  return midi.toArray();
+}
+
+function limbToGeneralMidi(limb: Limb): number {
+  // GM Drum Map
+  const map: Record<Limb, number> = {
+    "kick": 36,
+    "snare": 38,
+    "cross-stick": 37,
+    "hihat": 42,
+    "hihat-open": 46,
+    "ride": 51,
+    "ride-bell": 53,
+    "crash": 49,
+    "china": 52,
+    "splash": 55,
+    "tom-1": 50,
+    "tom-2": 47,
+    "tom-3": 45,
+  };
+  return map[limb];
+}
+```
+
+## Audio sample prompts
+
+When PatternTalk calls the audio service, the prompt includes both the pattern context and a style hint:
+
+```typescript
+interface AudioPrompt {
+  pattern: string;                // pattern name
+  limb?: Limb;                    // specific sample to generate
+  styleHints: string[];           // ["brutal drums", "18-inch china", "trashy"]
+  durationSeconds: number;        // 1-5 for one-shots, 5-15 for loops
+  intensity: "soft" | "medium" | "brutal" | "brutal-max";
+  loraAdapter?: string;           // "brutal-drums" by default
+}
+```
+
+Examples:
+- Limb-specific one-shot: `{ pattern: "D-Beat", limb: "china", styleHints: ["trashy", "18-inch", "panic-attack"], durationSeconds: 3, intensity: "brutal-max" }`
+- Loop preview: `{ pattern: "D-Beat", styleHints: ["brutal drums", "tight snare"], durationSeconds: 8, intensity: "brutal" }`
+
+## Training data manifest
+
+`data/training/manifest.yaml` describes every audio file used to train the brutal-drum LoRA.
+
+```yaml
+version: 1
+lora:
+  name: patterntalk-brutal-drums
+  base_model: stable-audio-3-small
+  training_steps: 1500
+  learning_rate: 1e-4
+  rank: 32
+
+samples:
+  - id: kick-001
+    path: oneshots/kick-tight.wav
+    category: kick
+    tags: [tight, clicky, triggered]
+    source: original-recording
+    license: CC-BY
+    duration_seconds: 1.2
+
+  - id: snare-discharge-001
+    path: oneshots/snare-trashy.wav
+    category: snare
+    tags: [trashy, snappy, crust]
+    source: freesound.org/user-x
+    license: CC-BY
+    duration_seconds: 0.8
+
+  - id: loop-dbeat-discharge-style
+    path: loops/dbeat-180.wav
+    category: loop
+    tags: [d-beat, 180bpm, discharge-style]
+    source: original-recording
+    license: CC-BY
+    duration_seconds: 4.0
+    bpm: 180
+```
+
+**License discipline:** All samples must be CC0, CC-BY, or original recordings. No unlicensed material. Documented in the manifest, surfaced in the model card.
+
+## What we're explicitly not modeling (yet)
+
+- User accounts (out of scope)
+- Cloud-saved pattern libraries (localStorage only)
+- Pattern remixing/chaining
+- Time-signature patterns other than 4/4 (the parser supports it but templates are 4/4)
+- Polymeter / metric modulation
+- Genre mixing (one pattern per request, not hybrids)
+
+These are all reasonable post-hackathon extensions.

docs/04-ux-voice-first.md

@@ -0,0 +1,388 @@
+# 04 — UX: Voice-First Design
+
+## Core principle
+
+**Voice is the primary surface. The visual grid is optional and layered.**
+
+A drummer with their hands full should be able to use PatternTalk without putting down sticks. A blind drummer using NVDA should be able to use it without sighted help. Sighted users get a parallel visual experience, but it never blocks the voice flow.
+
+## Voice technology
+
+### Speech-to-Text (STT)
+
+**Web Speech API: `SpeechRecognition`**
+
+```typescript
+const recognition = new (window.SpeechRecognition || window.webkitSpeechRecognition)();
+recognition.continuous = true;
+recognition.interimResults = true;
+recognition.lang = "en-US";
+
+recognition.onresult = (event) => {
+  const last = event.results[event.results.length - 1];
+  if (last.isFinal) {
+    onFinalTranscript(last[0].transcript.trim());
+  } else {
+    onInterimTranscript(last[0].transcript);
+  }
+};
+```
+
+**Compatibility:** Chrome, Edge, Safari. Firefox has it but disabled by default. For the hackathon demo, Chrome is the assumption.
+
+**Accessibility note:** Screenreaders (NVDA, VoiceOver) do NOT consume Web Speech API STT output — they have their own voice input path. So STT is for users *without* a screenreader or for users who want hands-free. Screenreader users will type or use their screenreader's voice control. Both paths converge on the same prompt parser.
+
+### Text-to-Speech (TTS)
+
+**Web Speech API: `SpeechSynthesis`**
+
+```typescript
+function speak(text: string, opts: { interrupt?: boolean } = {}) {
+  if (opts.interrupt) speechSynthesis.cancel();
+  const utterance = new SpeechSynthesisUtterance(text);
+  utterance.rate = 1.1;  // slightly faster than default for snappy feel
+  utterance.pitch = 1.0;
+  speechSynthesis.speak(utterance);
+}
+```
+
+**Voice selection:** Use the system default voice. No fancy custom voices — keeps the demo reliable across machines.
+
+**Accessibility note:** When a screenreader is active, `SpeechSynthesis` is muted by the screenreader (it doesn't double-speak). The text is read by the screenreader using the same DOM. This is exactly what we want.
+
+## The conversation loop
+
+PatternTalk maintains a state machine for voice interactions:
+
+```
+states: idle → listening → parsing → generating → ready → (next action)
+```
+
+### State diagram
+
+```
+[IDLE]
+  │ user clicks "Start" or presses Space
+  ▼
+[LISTENING]
+  │ mic captures audio
+  │ interim transcripts shown
+  │ user pauses or says a wake word
+  ▼
+[PARSING]
+  │ onomatopoeia matcher → pattern
+  │ prompt parser → ParsedRequest
+  │ tempo resolver → final tempo
+  ▼
+[GENERATING]
+  │ pattern engine → MIDI events
+  │ audio service → sample (async)
+  │ speak: "Generating skank beat, 4 bars..."
+  ▼
+[READY]
+  │ speak: "Skank beat ready. MIDI and sample generated.
+  │        Say 'play' to preview, 'regenerate' to try again,
+  │        'download MIDI', 'download sample',
+  │        or 'new pattern' to start over."
+  │
+  ├─ user: "play" → [PLAYING]
+  ├─ user: "regenerate" → [GENERATING] (4 variations possible)
+  ├─ user: "download MIDI" → trigger download
+  ├─ user: "download sample" → trigger download
+  └─ user: "new pattern" → [LISTENING]
+```
+
+### Wake word
+
+A simple wake word avoids the "always listening" creep:
+
+- **Wake word:** "PatternTalk" (or user-configurable)
+- After wake word, the system listens for one command
+- Optional: continuous listening mode for power users
+
+For the demo, "always listening with a push-to-talk toggle" is simpler. Use Spacebar or click to start/stop listening.
+
+## Voice commands
+
+### Generation commands
+
+| User says | System does |
+|---|---|
+| "Tupatupatupa on the hihat, 4 bars" | Generates skank beat (4 bars) |
+| "4 bars of d-beat riding the crash at 180" | Generates d-beat (4 bars, 180 BPM, ride-bell → crash override) |
+| "8 bars of skank beat" | Generates skank (8 bars, default tempo) |
+| "Triplet-driven double bass with accents on the one and the three" | Generates djent-polyrhythm (4 bars, default tempo, accents on 1 and 3) |
+| "Match my project tempo" | Sets `tempoSource = "reaper"` |
+| "Set tempo to 160" | Overrides tempo |
+| "Half-time feel" | Applies half-time modifier |
+| "Swing it" | Applies swing feel |
+
+### Action commands
+
+| User says | System does |
+|---|---|
+| "Play" / "Preview" | Plays the generated sample |
+| "Stop" | Stops playback |
+| "Regenerate" / "Try again" | Generates new variation |
+| "Variations" | Generates 4 variations |
+| "Pick number 2" | Selects variation 2 |
+| "Download MIDI" | Downloads .mid |
+| "Download sample" | Downloads .wav |
+| "New pattern" / "Start over" | Resets to listening |
+| "Help" | Reads command list |
+| "Repeat" | Re-speaks the last response |
+
+### Sample-generation commands
+
+| User says | System does |
+|---|---|
+| "Give me a trashy china" | Generates china one-shot |
+| "Snare sample, brutal" | Generates snare one-shot (intensity=brutal) |
+| "Loop preview" | Generates 8-second loop of current pattern |
+| "Tighter snare" | Generates snare variant |
+
+## Visual language — hardware / metallic reference
+
+The rack is styled as a hardware sampler. Source-of-truth visual reference:
+
+- **`toggle-switch.webp`** (repo root) — the metallic toggle-switch aesthetic to
+  match. Classic industrial 2-position toggle:
+  - **Chrome ball knob** on a **hexagonal metal housing** (reads as a polished
+    steel nut), seated in a **brushed-aluminum plate**.
+  - **Blue ON / red OFF** labels (colored inserts in the metal plate).
+  - Depth cues that sell it: specular highlight on the knob, drop shadow of the
+    knob onto the housing, inner shading on the hex recess, soft outer shadow on
+    the plate, clean bold sans-serif labels.
+- The existing engine rocker (`apps/web/app/globals.css` `.engine-toggle`) is the
+  in-app analog — brushed-steel two-position rocker. Keep any new toggle/switch
+  in the same metallic language (ball-on-hex for a literal toggle, brushed steel
+  for a rocker), not flat web styling.
+
+## Screen layout (visual fallback)
+
+When the user is sighted, the visual layout has these regions:
+
+```
+┌─────────────────────────────────────────────────────┐
+│ PatternTalk                            [help] [×]   │
+├─────────────────────────────────────────────────────┤
+│                                                     │
+│  🎤 [Listening...]                                  │
+│                                                     │
+│  You said: "tupatupatupa on the hihat, 4 bars"     │
+│                                                     │
+│  ┌───────────────────────────────────────────────┐ │
+│  │ Pattern: Skank Beat                           │ │
+│  │ Tempo: 120 BPM (say "match project")          │ │
+│  │ Bars: 4                                       │ │
+│  │ Status: Ready                                 │ │
+│  └───────────────────────────────────────────────┘ │
+│                                                     │
+│  ┌───────────────────────────────────────────────┐ │
+│  │ [Visual grid — bars of colored dots]          │ │
+│  │ ●K ●K ●S ●K ●K ●K ●S ●K                        │ │
+│  │ ●H ●H ●H ●H ●H ●H ●H ●H                        │ │
+│  └───────────────────────────────────────────────┘ │
+│                                                     │
+│  [Play]  [Download MIDI]  [Download Sample]         │
+│  [Regenerate]  [Variations (4)]  [New Pattern]     │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+**The visual grid is hidden by default** in voice-first mode. Sighted users can toggle it on. It's also hidden when a screenreader is detected (to reduce clutter, since the screenreader will read the description anyway).
+
+## Visual grid component
+
+For each bar in the pattern, render a row of dots:
+
+```
+Bar 1 of 4 — Skank Beat at 120 BPM
+● · ● · ● · ● ·     ← kick (red, larger)
+· ● · ● · ● · ●     ← snare (blue, smaller)
+● ● ● ● ● ● ● ●     ← hi-hat (yellow, medium)
+```
+
+Each limb has:
+- A color (configurable)
+- A size (kick = large, snare = medium, hi-hat = small)
+- A label tooltip on hover
+
+**Accessibility:** The grid has an `aria-label` summarizing the pattern:
+
+```html
+<div role="img" aria-label="Skank beat, 4 bars at 120 BPM. Kick on every beat with 8th note doubles. Snare on 2 and 4. Hi-hat on every 8th note.">
+  <!-- visual dots -->
+</div>
+```
+
+## Keyboard navigation
+
+Every action has a keyboard equivalent. No mouse required.
+
+| Key | Action |
+|---|---|
+| `Space` | Start/stop listening |
+| `Enter` | Confirm current selection / play preview |
+| `Tab` | Move focus through controls |
+| `1`-`4` | Pick variation N |
+| `M` | Download MIDI |
+| `S` | Download sample |
+| `R` | Regenerate |
+| `V` | Show variations |
+| `N` | New pattern |
+| `?` | Help (read command list) |
+| `Esc` | Cancel current action |
+
+Focus is always visible (high-contrast outline). When the screen announces something, focus moves to it so the screenreader reads it.
+
+## Pattern library page (`/library`)
+
+A separate page listing all patterns, with search and filter:
+
+- Search by name, tag, or genre
+- Filter by genre, tempo range
+- Click to load into the main UI
+- Share URL for any pattern (`/library?pattern=d-beat`)
+- "Fork" button: duplicate a pattern into the user's localStorage library
+
+**Accessibility:** Search is keyboard-driven. Results announced via `aria-live="polite"`. Filter chips have visible labels and ARIA states.
+
+## Variations UI
+
+When user asks for variations, show 4 mini-grids side by side:
+
+```
+┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
+│ Var 1    │ │ Var 2    │ │ Var 3    │ │ Var 4    │  [press 1-4]
+│ ●K ●K ●S │ │ ●K ●K ●K │ │ ●K ●K ●S │ │ ●K ●K ●S │
+│ ·  ·S ·  │ │ ·S ·  ·S │ │ ·  ·S ·  │ │ ·  ·S ·  │
+│ ●H ●H ●H │ │ ●H ●H ●H │ │ ●H ●H ●H │ │ ●H ●H ●H │
+└──────────┘ └──────────┘ └──────────┘ └──────────┘
+```
+
+Each variation has:
+- A different velocity humanization
+- A different micro-timing variation
+- Sometimes a different fill at the end of the bar
+- The patternId is the same; the variations are deterministic seeds of `engine.humanize()`
+
+For the demo, pre-generate 4 variations and store them so the picker is instant.
+
+## Sample preview player
+
+Audio playback uses the Web Audio API:
+
+```typescript
+async function playPreview(audioBuffer: ArrayBuffer) {
+  const ctx = new AudioContext();
+  const decoded = await ctx.decodeAudioData(audioBuffer);
+  const source = ctx.createBufferSource();
+  source.buffer = decoded;
+  source.connect(ctx.destination);
+  source.start(0);
+}
+```
+
+The preview loops until the user says "stop" or presses Esc.
+
+## Error handling
+
+Voice systems fail. The UX must handle it gracefully.
+
+| Failure | UX response |
+|---|---|
+| Mic permission denied | Show "Enable microphone in browser settings" + manual text input |
+| SpeechRecognition unavailable | Fall back to text input, show banner |
+| No onomatopoeia match | "I heard 'xyz', but I'm not sure what you mean. Try saying it differently, or pick from the list." |
+| Pattern not found | "Pattern 'xyz' not found. Did you mean 'd-beat'?" |
+| Audio service timeout | "Sample generation is taking longer than expected. Using cached sample. Say 'regenerate' to retry." |
+| Audio service error | "Couldn't generate a sample. MIDI is still ready. Say 'download MIDI' to save." |
+| Reaper not detected | "I don't see Reaper running. Say 'set tempo' to specify BPM manually." |
+
+In all cases, the user is told what's happening. No silent failures.
+
+## Performance budget
+
+| Metric | Target |
+|---|---|
+| First meaningful paint | < 1.5s |
+| Time to interactive (voice ready) | < 3s |
+| Prompt → MIDI generation | < 500ms (in-browser, no I/O) |
+| Prompt → sample ready | < 30s (cloud inference), < 5min acceptable (Vega inference) |
+| Voice transcript latency | < 500ms |
+| MIDI file download | < 200ms |
+
+## Demo flow (3–4 minutes)
+
+This is the rehearsal script:
+
+```
+[Open PatternTalk inside Reaper, mic icon visible]
+
+DRUMMER: "PatternTalk, tupatupatupa on the hihat, 4 bars"
+
+APP: "Skank beat, hi-hat upstrokes on the upbeats, 4 bars at 120 BPM.
+      MIDI ready. Sample ready."
+
+[Sighted users see grid + buttons. Blind drummer presses Tab to navigate.]
+
+DRUMMER: "Match my project tempo"
+
+APP: "Tempo set to 174 from Reaper project. Regenerating."
+
+APP: "Done. 4 bars at 174 BPM. Say 'play' to preview."
+
+DRUMMER: "Play"
+
+[Audio plays through speakers]
+
+DRUMMER: "Download MIDI"
+
+APP: "MIDI downloaded."
+
+[Drummer drags MIDI from browser downloads into Reaper track]
+
+DRUMMER: "Regenerate, brutal"
+
+APP: "Brutal mode engaged. Generating 4 variations."
+
+[4 mini-grids appear]
+
+DRUMMER: "Pick number 3"
+
+APP: "Variation 3 selected. Preview playing."
+
+DRUMMER: "New pattern. 4 bars of d-beat riding the crash at 180."
+
+APP: "D-beat with crash ride, 4 bars at 180. Generating."
+
+[Generation completes]
+
+DRUMMER: "Show me the grid."
+
+[Visual grid appears]
+
+[Switch on NVDA. Demo screenreader navigation.]
+
+DRUMMER: "Tab."
+
+NVDA: "Generate button. Tab. Regenerate button. Tab. Variations button..."
+
+DRUMMER: "Read the pattern."
+
+NVDA: "D-beat pattern. Kick plays on every beat with 8th-note doubles.
+       Snare hits on 2 and 4. Ride bell — no, crash — plays steady 8ths
+       throughout. 4 bars at 180 BPM."
+
+DRUMMER: "Download MIDI."
+
+[Done]
+```
+
+## What this UX is not
+
+- Not a chat interface. No typing back-and-forth. Voice is push-to-talk with clear states.
+- Not a visual-first app with voice features. Voice IS the app.
+- Not accessible as a feature. Accessibility is the design constraint that shaped voice-first.
+- Not a music theory tutor. We don't explain what a blast beat *means*, we just play it.

docs/05-accessibility.md

@@ -0,0 +1,294 @@
+# 05 — Accessibility Strategy
+
+## Why this isn't an afterthought
+
+PatternTalk's founder runs [Narwall.tech](https://narwall.tech), an accessibility testing tool that uses a real screenreader to find compliance gaps. The hackathon's Accessibility & Inclusion theme is listed as a first-class track. The target users include blind and visually impaired producers, a population currently locked out of almost every AI music tool.
+
+So accessibility is **load-bearing**, not a checklist. The voice-first design (see [`04-ux-voice-first.md`](04-ux-voice-first.md)) was driven by accessibility, not the other way around.
+
+## Principles
+
+1. **Test with real assistive technology, not just linters.** axe-core catches ~30% of issues. NVDA and VoiceOver catch the rest.
+2. **Voice-first is screenreader-first.** Building the voice layer well means the screenreader layer works for free.
+3. **Every action has a keyboard equivalent.** No mouse-only paths.
+4. **Every pattern has a textual description.** Not an afterthought caption — the description is the data.
+5. **No information conveyed by color alone.** The visual grid uses size, position, and label too.
+6. **Works at 200% zoom and at high contrast.** Tested with Windows High Contrast Mode.
+
+## Standards we comply with
+
+- **WCAG 2.2 AA** as the floor. AAA where feasible.
+- **WAI-ARIA 1.2** for semantic structure.
+- **Section 508** (US federal) — implicit via WCAG.
+- **EN 301 549** (EU) — implicit via WCAG.
+- **VPAT 2.4** — generated for the demo.
+
+## Screenreader support
+
+### Tested screenreaders
+
+| Screenreader | OS | Browser | Status |
+|---|---|---|---|
+| NVDA 2024.x | Windows | Firefox + Chrome | Primary test target |
+| VoiceOver | macOS | Safari | Primary test target |
+| JAWS 2024 | Windows | Chrome | Stretch target |
+| TalkBack | Android | Chrome | Post-hackathon |
+| VoiceOver | iOS | Safari | Post-hackathon |
+
+### Test cadence
+
+- **Before each commit to `main`** that touches the UI: axe-core in CI blocks on AA violations
+- **Once per day during the hackathon**: manual NVDA run-through of the full flow
+- **Before demo**: NVDA + VoiceOver run-through, both screenshare-able
+
+## Keyboard navigation
+
+Every interactive element is reachable via Tab. Focus order matches visual order. Focus is always visible (high-contrast outline).
+
+```css
+:focus-visible {
+  outline: 3px solid var(--focus-color, #FFD700);
+  outline-offset: 2px;
+}
+```
+
+Skip links for repeated UI:
+
+```html
+<a href="#main-content" class="skip-link">Skip to main content</a>
+<a href="#pattern-grid" class="skip-link">Skip to pattern grid</a>
+<a href="#controls" class="skip-link">Skip to controls</a>
+```
+
+### Roving tabindex for the visual grid
+
+The grid is a 2D structure. Arrow keys navigate within it; Tab enters/exits.
+
+```typescript
+function onGridKeydown(e: KeyboardEvent, row: number, col: number) {
+  switch (e.key) {
+    case "ArrowRight": moveFocus(row, col + 1); break;
+    case "ArrowLeft":  moveFocus(row, col - 1); break;
+    case "ArrowDown":  moveFocus(row + 1, col); break;
+    case "ArrowUp":    moveFocus(row - 1, col); break;
+    case "Home":       moveFocus(row, 0); break;
+    case "End":        moveFocus(row, lastCol); break;
+    case "Enter":      announceCurrentCell(); break;
+  }
+}
+```
+
+## Voice interaction as accessibility
+
+### How voice maps to screenreaders
+
+When PatternTalk speaks via `SpeechSynthesis`:
+
+- **No screenreader active:** audio plays through speakers, user hears it
+- **NVDA active:** NVDA mutes the speech synthesis output and reads the same text via its own voice, using the live region's text content
+- **VoiceOver active:** same behavior as NVDA
+
+This is the magic: a single voice output layer works for everyone.
+
+### How STT maps to screenreaders
+
+Screenreaders don't expose their STT input to web pages. So:
+
+- **Sighted users without screenreader:** use Web Speech API STT
+- **Screenreader users:** type into a regular text input, or use their screenreader's voice control (e.g., Dragon, Voice Access on Android, Voice Control on macOS)
+
+Both paths converge on the same prompt parser. The UI offers both visibly:
+
+```
+[🎤 Hold Space to talk]  or  [Type a prompt: ____________]
+```
+
+### ARIA live regions
+
+When PatternTalk wants to announce something (a new pattern generated, an error, a status change), it uses ARIA live regions:
+
+```html
+<div aria-live="polite" aria-atomic="true" id="status">
+  <!-- PatternTalk writes here when state changes -->
+  Skank beat, 4 bars at 174 BPM. MIDI ready.
+</div>
+
+<div aria-live="assertive" role="alert" id="errors">
+  <!-- Errors go here, interrupt speechreader -->
+</div>
+```
+
+**Polite** for routine status (don't interrupt). **Assertive** for errors (interrupt).
+
+## Pattern description format
+
+Every pattern has a screenreader-friendly text description. The format:
+
+```
+{Pattern name}. {Genre} at {tempo} BPM.
+{Limb-by-limb description}.
+{Notable characteristics}.
+{Tags/context}.
+```
+
+Examples:
+
+**D-Beat:**
+```
+D-Beat. Metal at 180 BPM. Kick plays on every beat with
+8th-note doubles. Snare hits on 2 and 4. Ride bell plays
+steady 8th notes throughout. Common in Discharge, Entombed,
+and Scandinavian crust punk.
+```
+
+**Skank Beat:**
+```
+Skank Beat. Ska at 120 BPM. Kick on 1 and 3. Snare on
+2 and 4. Hi-hat plays on every upbeat — the "and" of each
+beat. Ska upstroke feel.
+```
+
+**Blast Traditional:**
+```
+Traditional Blast Beat. Metal at 200 BPM. Kick and snare
+alternate in 8th notes throughout. Hi-hat plays continuous
+8th notes. High intensity.
+```
+
+**Djent Polyrhythm:**
+```
+Djent Polyrhythm. Metal at 140 BPM. Kick plays a 4-over-3
+polyrhythm against the 4/4 pulse. Snare on 2 and 4.
+Ride cymbal plays 8th notes. Polyphonic, Meshuggah-style.
+```
+
+The description is generated from the template at runtime. Sighted users see it in a panel; screenreaders read it on demand.
+
+## High contrast and theming
+
+```css
+:root {
+  --bg: #ffffff;
+  --fg: #1a1a1a;
+  --accent: #0066cc;
+  --focus: #ffd700;
+  --limb-kick: #d62828;
+  --limb-snare: #1d3557;
+  --limb-hihat: #f4a261;
+  --limb-ride: #2a9d8f;
+  --limb-crash: #e76f51;
+  --limb-china: #8338ec;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #1a1a1a;
+    --fg: #f0f0f0;
+    --accent: #66b2ff;
+  }
+}
+
+@media (prefers-contrast: more) {
+  :root {
+    --fg: #000000;
+    --bg: #ffffff;
+    --accent: #0000ee;
+    --focus: #ff00ff;
+  }
+}
+```
+
+## Reduced motion
+
+Some users get sick from animation. Respect `prefers-reduced-motion`:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+The visual grid has subtle "pulse" animations when patterns play back. With reduced motion, those are disabled — only color changes indicate playback position.
+
+## Captions and transcripts
+
+Every audio sample generated by SA3 gets a textual caption (derived from the prompt + pattern context):
+
+```
+Sample: brutal china crash, 18-inch, trashy.
+Duration: 3.0 seconds. Intensity: brutal-max.
+```
+
+Captions are:
+- Visible by default in the UI
+- Read by screenreaders when focus moves to the sample player
+- Exportable as a sidecar text file with the .wav download
+
+## CI accessibility checks
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+jobs:
+  a11y:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npm run build
+      - run: npm run test:a11y   # axe-core via @axe-core/playwright
+```
+
+`npm run test:a11y` runs Playwright with axe-core against every page. Fails on any WCAG AA violation.
+
+## Manual screenreader test protocol
+
+Before each demo:
+
+1. **Cold start:** Close browser, open PatternTalk, immediately start NVDA
+2. **Full flow via keyboard only:** Generate a pattern, audition it, download MIDI, generate variations, pick one, start over
+3. **Verify announcements:** Every state change should be announced within 1 second
+4. **Verify focus:** Focus should never get stuck or disappear
+5. **Verify grid:** Tab to grid, arrow-navigate, every cell announces its limb and velocity
+6. **Verify download:** Download MIDI and sample, verify file names announced
+7. **Verify errors:** Trigger an error path (e.g., Reaper not running), verify error is announced politely
+8. **VoiceOver pass:** Repeat steps 1–7 with VoiceOver on macOS
+
+A short screen recording of this is part of the demo deliverables.
+
+## Reduced-physical-load mode (stretch)
+
+For drummers with RSI, chronic pain, or temporary injury. The plugin generates the physically demanding parts (blast beats, double bass) and the drummer plays the parts they can play.
+
+Implementation: split each pattern into "AI plays" vs "you play" subsets. Export two MIDI tracks. Drummer mutes the AI track they want to play themselves.
+
+Not in scope for the 2-day hackathon, but the data model supports it (each `Hit` has a `playableBy: "ai" | "human"` flag).
+
+## Haptic metronome (stretch)
+
+A paired PWA on the drummer's phone vibrates on the beat. Different vibration patterns for downbeat, backbeat, fills.
+
+Out of scope for the 2-day hackathon. Post-hackathon product.
+
+## Real-time audio captioning (stretch)
+
+Capture audio from the interface, run lightweight audio classification, output live captions: "kick, snare, kick-snare fill, china crash."
+
+Out of scope for the 2-day hackathon. This is what would make the tool usable for deaf producers collaborating with hearing producers.
+
+## Why this matters for the hackathon
+
+Jury includes Andrew Huang, who has explicitly designed for accessibility in past work. Zack Zukowski (Stability AI) is known for caring about inclusive design. The "Accessibility & Inclusion" theme is a first-class track. The MUTEK Festival, where winners present, has an audience that includes accessibility advocates.
+
+A demo that opens with "let me show you the screenreader view" is memorable. A demo that says "and we tested this with NVDA daily" is credible.
+
+## Narwall integration (post-hackathon)
+
+Long-term, PatternTalk could be tested *by* Narwall as part of its workflow — using Narwall's real-screenreader-based testing to continuously verify that no UI regression breaks the screenreader experience. That's a natural fit for the founder's other product and would make PatternTalk the only music tool with continuous accessibility testing baked in.
+
+For the hackathon: mention this as the long-term plan in the demo, don't build the integration.

docs/06-stable-audio-integration.md

@@ -0,0 +1,466 @@
+# 06 — Stable Audio 3 Integration
+
+## What we're using Stable Audio 3 for
+
+PatternTalk uses SA3 for two things, both explicitly listed in the Stability AI challenge brief:
+
+1. **One-shot sample generation** — "give me a trashy 18-inch china"
+2. **Loop preview generation** — 5–15 second previews of patterns with brutal drum styling
+
+Plus one bonus use case:
+
+3. **LoRA fine-tuning** — train a small adapter on brutal drum samples so the model actually understands the genre
+
+The MIDI patterns themselves are NOT generated by SA3. They're hand-coded templates. This is a deliberate split: SA3's strength is sample quality, not structured MIDI generation.
+
+## Why local inference, not API
+
+The Stability AI challenge explicitly rewards *"showing the strengths of local open models."* Using the open weights locally:
+
+- Proves we actually use the open model, not a black-box API
+- Eliminates rate limits and surprise outages during the demo
+- Lets us fine-tune and ship the LoRA weights as a deliverable
+- Makes the inference reproducible and inspectable
+
+We pay for this with slower inference on consumer hardware. Mitigation: cloud GPU for the heavy work.
+
+## Hardware reality
+
+### Vega 56 (your machine) — honest assessment
+
+**Specs:** 8GB HBM2, GCN 5th gen, ROCm-supported but old.
+
+**Inference (SA3 small):**
+- ✅ Fits in 8GB VRAM in fp16
+- ⚠️ Tight memory headroom — no concurrent inference, no batching
+- ⚠️ ROCm + PyTorch + audio models = some setup friction
+- ⚠️ Throughput roughly **1/4 to 1/6 of an RTX 4090** on diffusion models
+- ⚠️ A 30-second sample at 100 denoising steps: expect 2–10 minutes wall time
+
+**Fine-tuning (LoRA):**
+- ❌ Not practical. Gradient buffers + optimizer state blow past 8GB.
+- ⏱️ If forced: 10–50× slower than cloud. Full LoRA training: hours to days, not feasible in a hackathon.
+
+**Verdict:** Use Vega for development and testing the inference path. Use cloud GPU for fine-tuning and demo-day inference.
+
+### Cloud GPU (RunPod / Vast.ai / Modal)
+
+**Recommended for the hackathon:**
+
+| Provider | GPU | Cost/hr | Notes |
+|---|---|---|---|
+| RunPod | RTX 4090 | $0.40 | Easiest UX, instant deploy |
+| RunPod | A4000 | $0.30 | Slightly slower than 4090 |
+| Vast.ai | RTX 3090 | $0.20 | Cheaper, more setup |
+| Modal | A10G | $0.50 | Serverless, pay per second |
+| Lambda Labs | A100 | $1.10 | Overkill but fast |
+
+**Recommendation:** RunPod with a 4090 for ~6 hours total = **~$3**. Fine-tune during one session, run demo inference during another.
+
+## Setup
+
+### Step 1: Get the model weights
+
+```bash
+# Clone the repo
+git clone https://github.com/Stability-AI/stable-audio-3.git
+cd stable-audio-3
+
+# Request access on HuggingFace (gated)
+# https://huggingface.co/stabilityai/stable-audio-3-small
+# https://huggingface.co/stabilityai/stable-audio-3-medium
+
+# Login
+huggingface-cli login
+
+# Download weights (use small on Vega, medium on cloud)
+python scripts/download_weights.py --model small
+```
+
+### Step 2: Install dependencies (local, Vega)
+
+ROCm is finicky. Use a pre-built PyTorch container if possible.
+
+```bash
+# Option A: Use the official Stability AI Docker image
+docker pull stabilityai/stable-audio-tools:latest
+
+# Option B: Manual install (if Docker fails)
+pip install torch==2.4.0 --index-url https://download.pytorch.org/whl/rocm5.7
+pip install stable-audio-tools
+pip install fastapi uvicorn
+```
+
+**Reality check:** On Vega, expect 1–3 hours of yak-shaving to get inference running the first time. Budget for this.
+
+### Step 3: Verify inference works
+
+```python
+# scripts/smoke_test.py
+from stable_audio_tools import get_pretrained_model
+from stable_audio_tools.inference.generation import generate_diffusion_cond
+
+model, config = get_pretrained_model("stabilityai/stable-audio-3-small")
+
+# Time this — establishes your baseline
+import time
+start = time.time()
+output = generate_diffusion_cond(
+    model,
+    steps=100,
+    cfg_scale=7,
+    conditioning=[{"prompt": "d-beat drum loop, 180 BPM, brutal", "seconds_start": 0, "seconds_total": 8}],
+    batch_size=1,
+    sample_size=44100 * 8,
+    device="cuda",
+)
+elapsed = time.time() - start
+print(f"Generated in {elapsed:.1f}s")
+# Save output
+import torchaudio
+torchaudio.save("smoke_test.wav", output.squeeze().cpu(), 44100)
+```
+
+If this takes < 2 minutes on Vega, you're fine. If it takes > 10 minutes, commit to cloud GPU for the demo.
+
+## Fine-tuning: brutal-drum LoRA
+
+### Why fine-tune
+
+Off-the-shelf SA3 doesn't know "brutal" drums. Your testing confirmed it. Fine-tuning on a curated dataset makes the model actually understand the genre vocabulary.
+
+### Training data curation
+
+**Minimum viable dataset (start with this):**
+
+- 20–40 one-shots:
+  - 5–10 kicks (tight, clicky, triggered)
+  - 5–10 snares (snappy, trashy, mid-range)
+  - 3–5 chinas (trashy, dark, bright variants)
+  - 3–5 crashes (various sizes/washes)
+  - 2–3 hi-hats (closed, open, stack)
+  - 2–3 rides (dry, washy, bell-forward)
+- 10–20 loops (3–10 seconds each):
+  - 3–5 d-beat loops at various tempos
+  - 3–5 blast beat loops (traditional, hammer, hyperblast)
+  - 2–3 half-time grooves
+  - 2–3 punk rock / hardcore loops
+  - 2–3 djent polyrhythm loops
+
+**Sources (in order of preference):**
+
+1. **Your own recordings** — best, no licensing issues, your taste
+2. **Freesound.org** — filter to CC0 or CC-BY, document the user
+3. **Splice / Loopcloud** — if you have a subscription, export with licensing documented
+4. **Bandcamp / label sample packs** — check license terms, some are CC-BY
+5. **Your band's existing recordings** — if you produced them, you own them
+
+**Discipline:** Every file in `data/training/` has a corresponding entry in `data/training/manifest.yaml` with source, license, duration, BPM (for loops), and tags.
+
+### Pre-processing
+
+All samples normalized to:
+- WAV format
+- 44100 Hz sample rate (or 48000 — match SA3's expected rate)
+- Mono (drums don't need stereo for LoRA training; stereo adds noise)
+- Loudness normalized to ~ -14 LUFS
+- Trimmed silence at start/end
+- Loops: aligned to bar boundaries, ideally with a single downbeat
+
+```python
+# services/audio/training/preprocess.py
+import torchaudio
+import pyloudnorm as pyln
+
+def preprocess(input_path: str, output_path: str):
+    waveform, sr = torchaudio.load(input_path)
+    # Resample
+    if sr != 44100:
+        waveform = torchaudio.functional.resample(waveform, sr, 44100)
+    # To mono
+    waveform = waveform.mean(dim=0, keepdim=True)
+    # Loudness normalize
+    meter = pyln.Meter(44100)
+    loudness = meter.integrated_loudness(waveform.numpy().T)
+    normalized = pyln.normalize.loudness(waveform.numpy().T, loudness, -14.0)
+    waveform = torch.from_numpy(normalized.T).unsqueeze(0)
+    torchaudio.save(output_path, waveform, 44100)
+```
+
+### LoRA training script
+
+Stability's repo supports LoRA via `stable_audio_tools.training.lora`. Use their example as a base.
+
+```python
+# services/audio/training/train_lora.py
+import torch
+from stable_audio_tools.models import create_model_from_config
+from stable_audio_tools.training.lora import LoRADataset, LoRATrainer
+from stable_audio_tools.data.utils import load_training_manifest
+
+# Load base model
+model, config = create_model_from_config("model_config.json")
+model.load_state_dict(torch.load("stable_audio_3_small.safetensors"))
+
+# Load training manifest
+dataset = LoRADataset(
+    manifest_path="data/training/manifest.yaml",
+    audio_dir="data/training/",
+)
+
+# LoRA config
+lora_config = {
+    "rank": 32,
+    "alpha": 32,
+    "dropout": 0.05,
+    "target_modules": ["to_q", "to_k", "to_v", "to_out.0"],  # SA3 specifics
+}
+
+# Train
+trainer = LoRATrainer(
+    model=model,
+    dataset=dataset,
+    lora_config=lora_config,
+    learning_rate=1e-4,
+    batch_size=2,
+    gradient_accumulation=4,
+    max_steps=1500,
+    save_every=500,
+    output_dir="loras/brutal-drums",
+    device="cuda",
+)
+
+trainer.train()
+```
+
+**Expected training time on RTX 4090:** 30–90 minutes for 1500 steps with rank 32.
+
+**Output:**
+- `loras/brutal-drums/adapter.safetensors` — the LoRA weights (~50MB)
+- `loras/brutal-drums/checkpoints/` — intermediate checkpoints
+- `loras/brutal-drums/training_log.json` — loss curve
+
+### Publishing the LoRA
+
+After training, push to HuggingFace:
+
+```python
+# services/audio/training/publish.py
+from huggingface_hub import HfApi
+
+api = HfApi()
+api.create_repo("your-username/patterntalk-brutal-drums", repo_type="model")
+
+api.upload_folder(
+    folder_path="loras/brutal-drums/",
+    repo_id="your-username/patterntalk-brutal-drums",
+    commit_message="Initial LoRA trained on brutal drum samples",
+)
+
+# Upload model card
+api.upload_file(
+    path_or_fileobj="loras/brutal-drums/README.md",
+    path_in_repo="README.md",
+    repo_id="your-username/patterntalk-brutal-drums",
+)
+```
+
+**Model card must include:**
+- Base model reference
+- Training data summary (with manifest link)
+- License
+- Intended use
+- Limitations (it's a LoRA, not general-purpose)
+- Citation to Stability AI and PatternTalk
+
+## Inference service
+
+### Architecture
+
+```python
+# services/audio/sa3/server.py
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+import torch
+from stable_audio_tools import get_pretrained_model
+from stable_audio_tools.inference.generation import generate_diffusion_cond
+import torchaudio
+import io
+import hashlib
+
+app = FastAPI()
+
+# Load model once at startup
+model, config = get_pretrained_model("stabilityai/stable-audio-3-small")
+model = model.to("cuda")
+model.eval()
+
+# Load LoRA adapter
+model.load_adapter("loras/brutal-drums/adapter.safetensors", adapter_name="brutal")
+
+# Sample cache (LRU + disk)
+cache_dir = Path("cache/")
+cache_dir.mkdir(exist_ok=True)
+
+class GenerateRequest(BaseModel):
+    prompt: str
+    duration_seconds: float = 8.0
+    intensity: str = "medium"  # soft | medium | brutal | brutal-max
+    use_lora: bool = True
+    cfg_scale: float = 7.0
+    steps: int = 100
+
+class GenerateResponse(BaseModel):
+    audio_url: str  # URL to download the WAV
+    prompt: str
+    duration: float
+    cached: bool
+
+@app.post("/generate", response_model=GenerateResponse)
+async def generate(req: GenerateRequest):
+    # Cache key
+    cache_key = hashlib.sha256(
+        f"{req.prompt}|{req.duration_seconds}|{req.intensity}|{req.use_lora}".encode()
+    ).hexdigest()[:16]
+
+    cache_path = cache_dir / f"{cache_key}.wav"
+
+    if cache_path.exists():
+        return GenerateResponse(
+            audio_url=f"/cache/{cache_key}.wav",
+            prompt=req.prompt,
+            duration=req.duration_seconds,
+            cached=True,
+        )
+
+    # Build conditioning
+    conditioning = [{
+        "prompt": req.prompt,
+        "seconds_start": 0,
+        "seconds_total": req.duration_seconds,
+    }]
+
+    # Apply LoRA
+    if req.use_lora:
+        model.set_adapter("brutal")
+    else:
+        model.disable_adapters()
+
+    # Generate
+    try:
+        output = generate_diffusion_cond(
+            model,
+            steps=req.steps,
+            cfg_scale=req.cfg_scale,
+            conditioning=conditioning,
+            sample_size=int(44100 * req.duration_seconds),
+            device="cuda",
+        )
+    except Exception as e:
+        raise HTTPException(500, f"Generation failed: {e}")
+
+    # Save
+    torchaudio.save(str(cache_path), output.squeeze().cpu(), 44100)
+
+    return GenerateResponse(
+        audio_url=f"/cache/{cache_key}.wav",
+        prompt=req.prompt,
+        duration=req.duration_seconds,
+        cached=False,
+    )
+
+@app.get("/cache/{key}.wav")
+async def get_cached(key: str):
+    path = cache_dir / f"{key}.wav"
+    if not path.exists():
+        raise HTTPException(404)
+    return FileResponse(path)
+```
+
+### Intensity → prompt engineering
+
+Map user-friendly intensity to model-friendly prompts:
+
+```python
+INTENSITY_PROMPTS = {
+    "soft": "clean studio drums, polished, tight, controlled",
+    "medium": "live room drums, punchy, present",
+    "brutal": "brutal drums, trashy, aggressive, raw, distorted",
+    "brutal-max": "ultra-brutal drums, completely destroyed, blown-out, panic-attack intensity",
+}
+
+def build_audio_prompt(req: AudioPrompt) -> str:
+    parts = [
+        req.pattern,
+        req.styleHints.join(", "),
+        INTENSITY_PROMPTS[req.intensity],
+        "drum recording, close-mic'd",
+    ]
+    if req.limb:
+        parts.append(f"single {req.limb} hit")
+    return ", ".join(filter(None, parts))
+```
+
+## Prompting strategy for SA3
+
+Stable Audio 3 responds well to:
+- Genre terms ("d-beat", "black metal", "brutal")
+- Tempo ("180 BPM")
+- Recording style ("close-mic'd", "room mic", "triggered")
+- Specific instrument descriptors ("tight snare", "trashy china")
+- Intensity adjectives ("brutal", "raw", "polished")
+
+SA3 responds poorly to:
+- Vague aesthetic terms ("cool", "interesting")
+- Mixing many genres ("jazz-black-metal-funk")
+- Trying to specify timing ("snare on the and of 2")
+
+Our brutal-drum LoRA biases the model toward:
+- Recognizing metal subgenres
+- Generating physically realistic drum sounds
+- Avoiding pop/EDM patterns
+
+## Demo strategy
+
+For the live demo, we want generation to be fast and reliable. Pre-generate a few showcase samples:
+
+```bash
+# Pre-generate demo cache
+python scripts/pregenerate_demo.py
+# Generates:
+#   cache/dbeat-180.wav
+#   cache/blast-traditional-200.wav
+#   cache/china-trashy.wav
+#   cache/kick-brutal.wav
+#   cache/skank-120.wav
+#   cache/variation-1.wav ... variation-4.wav
+```
+
+During the demo, hit the live API for the "regenerate" command (to show inference happening), but rely on cache for the initial generation to keep the demo snappy.
+
+## What can go wrong
+
+| Failure | Mitigation |
+|---|---|
+| Cloud GPU instance dies | Pre-generated cache + fallback to Vega inference |
+| SA3 produces generic output | LoRA adapter handles this; fallback is to label output "demo variation" |
+| Generation exceeds 30s | Show progress indicator + have pre-generated fallback |
+| Audio quality is bad | Iterate on LoRA training data; have multiple variations to pick from |
+| ROCm issues on Vega | Skip local dev, use cloud-only |
+
+## Cost summary
+
+| Item | Cost |
+|---|---|
+| Cloud GPU (RunPod 4090, 6 hours total) | ~$3 |
+| HuggingFace Pro (if needed for gated weights) | $0 (free tier sufficient) |
+| Total cloud spend | **~$3** |
+
+If your budget is truly $0, do everything on Vega and accept 2–10 minute inference times. The product still works, the demo just needs more buffer time.
+
+## Post-hackathon
+
+- Quantize the model (int8) for faster inference
+- Train additional LoRAs: rock, jazz, funk (one per genre)
+- Host inference on Modal/Replicate for public use
+- Build a "train your own LoRA" UI — the "personal LoRA trainer" use case from the brief

docs/07-reaper-integration.md

@@ -0,0 +1,305 @@
+# 07 — Reaper Integration
+
+## Goal
+
+PatternTalk lives alongside Reaper, not inside it (for the 2-day hackathon). Integration happens at three levels:
+
+1. **Auto-detect project tempo** via Reaper's Web Control surface
+2. **MIDI export** that's drag-and-droppable into Reaper
+3. **Optional ReaScript bridge** for richer control (stretch)
+
+The CLAP plugin wrap is a stretch goal — see [`02-architecture.md`](02-architecture.md#decision-5-reaper-first-daw-integration).
+
+## Reaper Web Control surface
+
+Reaper has a built-in HTTP server you can enable in Preferences → Control Surfaces → Web Browser Interface.
+
+**Default URL:** `http://localhost:8080`
+
+**Default endpoints we care about:**
+
+| Endpoint | Returns |
+|---|---|
+| `GET /_/` | HTML control panel (we ignore this) |
+| `GET /_/action?name=...` | Run a named action |
+| `GET /_/set?param=value` | Set a parameter |
+| `WS ws://localhost:8080/_/` | WebSocket for live state |
+
+**Project tempo** is exposed via the WebSocket. On connect:
+
+```json
+{
+  "type": "state",
+  "data": {
+    "tempo": 174,
+    "timesig": [4, 4],
+    "playstate": 0,
+    "position": 0
+  }
+}
+```
+
+We subscribe to `state` updates and use the current tempo as the default for new patterns.
+
+## Client-side Reaper detection
+
+```typescript
+// apps/web/lib/reaper/client.ts
+
+class ReaperClient {
+  private socket: WebSocket | null = null;
+  private listeners: Set<(state: ReaperState) => void> = new Set();
+  private state: ReaperState = {
+    connected: false,
+    tempo: null,
+    timeSignature: null,
+  };
+
+  async connect(): Promise<boolean> {
+    try {
+      this.socket = new WebSocket("ws://localhost:8080/_/");
+      this.socket.onopen = () => {
+        this.state.connected = true;
+        this.notify();
+      };
+      this.socket.onmessage = (event) => {
+        const msg = JSON.parse(event.data);
+        if (msg.type === "state") {
+          this.state.tempo = msg.data.tempo;
+          this.state.timeSignature = msg.data.timesig;
+          this.notify();
+        }
+      };
+      this.socket.onerror = () => {
+        this.state.connected = false;
+        this.notify();
+      };
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  getTempo(): number | null {
+    return this.state.tempo;
+  }
+
+  isConnected(): boolean {
+    return this.state.connected;
+  }
+
+  subscribe(listener: (state: ReaperState) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private notify() {
+    for (const listener of this.listeners) {
+      listener(this.state);
+    }
+  }
+}
+
+interface ReaperState {
+  connected: boolean;
+  tempo: number | null;
+  timeSignature: [number, number] | null;
+}
+
+export const reaper = new ReaperClient();
+```
+
+## Tempo resolution priority
+
+When the user generates a pattern, PatternTalk picks the tempo in this order:
+
+1. **Explicit in prompt:** "set tempo to 160" or "180 BPM" → 160 or 180
+2. **From Reaper project:** If connected → use project tempo
+3. **From uploaded audio:** If user uploaded an audio file → detected BPM
+4. **Default:** 120 BPM
+
+```typescript
+// apps/web/lib/parser/tempo.ts
+
+export async function resolveTempo(
+  parsed: ParsedRequest,
+  reaper: ReaperClient,
+  uploadedAudio: AudioBuffer | null
+): Promise<number> {
+  if (parsed.tempo) {
+    return { tempo: parsed.tempo, source: "prompt" };
+  }
+
+  if (reaper.isConnected() && reaper.getTempo()) {
+    return { tempo: reaper.getTempo()!, source: "reaper" };
+  }
+
+  if (uploadedAudio) {
+    const bpm = await detectBpm(uploadedAudio);
+    if (bpm) {
+      return { tempo: bpm, source: "audio" };
+    }
+  }
+
+  return { tempo: 120, source: "default" };
+}
+```
+
+## MIDI export
+
+The MIDI file is generated in-browser. The user downloads it as a `.mid` file, then drags it onto a Reaper track.
+
+### File naming
+
+```
+patterntalk-{pattern-id}-{bars}bars-{bpm}bpm-{timestamp}.mid
+```
+
+Examples:
+- `patterntalk-d-beat-4bars-180bpm-2026-08-22T1430Z.mid`
+- `patterntalk-skank-4bars-120bpm-2026-08-22T1435Z.mid`
+
+### Drag-and-drop into Reaper
+
+Reaper accepts MIDI files dropped from the file system onto a track. We make this explicit:
+
+```typescript
+// apps/web/components/midi/DownloadButton.tsx
+
+function downloadMidi(events: MidiEvent[], meta: PatternMeta) {
+  const midi = eventsToMidi(events, meta);
+  const blob = new Blob([midi], { type: "audio/midi" });
+  const url = URL.createObjectURL(blob);
+
+  const filename = `patterntalk-${meta.patternId}-${meta.bars}bars-${meta.bpm}bpm-${new Date().toISOString()}.mid`;
+
+  // Trigger download
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+
+  // Cleanup
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+
+  return filename;
+}
+```
+
+### Drag-from-browser directly into Reaper
+
+For the smoothest demo, the MIDI file should be draggable from the browser window directly onto a Reaper track. Reaper accepts this if the file is exposed as a real file (not a Blob URL), which means we need to keep the file in memory and reference it via the DataTransfer API.
+
+```typescript
+function makeMidiDraggable(
+  events: MidiEvent[],
+  meta: PatternMeta,
+  element: HTMLElement
+) {
+  const midi = eventsToMidi(events, meta);
+  const filename = `patterntalk-${meta.patternId}-${meta.bars}bars-${meta.bpm}bpm.mid`;
+
+  element.draggable = true;
+  element.ondragstart = (e) => {
+    const file = new File([midi], filename, { type: "audio/midi" });
+    e.dataTransfer!.files = [file];
+    // Some browsers need this
+    e.dataTransfer!.setData("DownloadURL", `audio/midi:${filename}:${e.dataTransfer!.getData("DownloadURL")}`);
+  };
+}
+```
+
+**Caveat:** Browser support for dragging real files (not blob URLs) into native apps varies. Test in Chrome on the demo machine before relying on this.
+
+If drag-from-browser is flaky, the fallback is "click to download, then drag from Downloads folder to Reaper." Annoying but reliable.
+
+## Verifying MIDI works in Reaper
+
+Before the demo, smoke-test the MIDI export:
+
+1. Open Reaper, create a new project at 180 BPM, 4/4
+2. Add a track, load any drum sampler VST (free options: Drumgizmo, MT Power Drum Kit, or Reaper's built-in ReaDrumCrafter)
+3. Download a PatternTalk MIDI file
+4. Drag onto the track
+5. Hit play — confirm the pattern plays correctly
+
+Common bugs to watch for:
+- Tempo mismatch (Reaper plays at project tempo; MIDI file tempo should match)
+- Wrong GM drum map notes (kick = 36, snare = 38, etc.)
+- Notes too short or too long (drum hits should be very short, ~1-10 ticks)
+- MIDI file doesn't import at all (file format corruption)
+
+## ReaScript bridge (stretch)
+
+For richer integration, a small ReaScript can:
+
+- Auto-create a new track and load the MIDI when PatternTalk generates
+- Set the project tempo to match the pattern
+- Start playback automatically
+
+```lua
+-- scripts/reaper/patterntalk_bridge.lua
+
+-- Receives HTTP requests from PatternTalk
+-- Endpoint: http://localhost:8081/...
+
+-- For each request, execute a Reaper action
+
+function onRequest(method, path, body)
+  if path == "/import-midi" then
+    local filepath = body.filepath
+    local trackIndex = body.trackIndex or 0
+    Reaper.MIDI_InsertMedia(filepath, trackIndex)
+    return { ok = true }
+  end
+
+  if path == "/set-tempo" then
+    local tempo = body.tempo
+    reaper.SetProjectTimeSignature(0, tempo, ...)
+    return { ok = true }
+  end
+end
+```
+
+This is a stretch goal. If we have a teammate who's comfortable with ReaScript, we ship it. If not, the Web Control surface + MIDI drag-and-drop is the integration story.
+
+## Web Control endpoint reference
+
+The full Reaper Web Control API is documented at:
+https://www.reaper.fm/developers/webcontrol.php
+
+Key endpoints for PatternTalk:
+
+| Action | Endpoint |
+|---|---|
+| Get full state | `WS /_/` |
+| Run named action | `GET /_/action?name=<action_id>` |
+| Set project tempo | `GET /_/set?project_tempo=<bpm>` |
+| Get current tempo | (via WebSocket state) |
+| Transport play | `GET /_/action?name=40044` (transport: play) |
+| Transport stop | `GET /_/action?name=40044` (toggle, state-dependent) |
+
+**Note:** Reaper's Web Control API is reverse-engineered more than documented. The state format isn't formally specced. Expect some brittleness; verify on the actual Reaper version (currently 7.x).
+
+## Demo integration flow
+
+For the live demo, the integration sequence is:
+
+1. **Reaper is already open** with a project at ~174 BPM (a typical d-beat tempo)
+2. **PatternTalk opens** in a browser window next to Reaper
+3. **PatternTalk detects Reaper**, announces "Reaper connected at 174 BPM"
+4. **User generates a pattern** — PatternTalk uses 174 from Reaper
+5. **User downloads or drags MIDI** — drops into a Reaper track with a drum VST
+6. **Reaper plays** — pattern sounds correct
+7. **Optional:** Change Reaper project tempo to 160, regenerate in PatternTalk, drag new MIDI, plays at new tempo
+
+The whole sequence, with audio, takes about 30 seconds. Memorable.
+
+## What this integration is NOT
+
+- Not a VST/AU/CLAP plugin (stretch goal only)
+- Not bidirectional — PatternTalk reads from Reaper, doesn't write project state
+- Not automatic — user still has to drag the MIDI file in
+- Not a replacement for Reaper's built-in features
+
+This is intentional. The 80/20 here is "auto-detect tempo + clean MIDI export." Everything else is stretch.

docs/08-build-plan.md

@@ -0,0 +1,244 @@
+# 08 — Build Plan
+
+## Timeline overview
+
+```
+NOW (3 weeks before)        Pre-hack prep
+HACK DAY 1 (Sat Aug 22)     Build core features
+HACK DAY 2 (Sun Aug 23)     Polish, integrate, demo
+POST-HACK                   Publish, ship, follow up
+```
+
+## Pre-hackathon (you have ~3 weeks)
+
+Goal: arrive at the event with a working skeleton, training data ready, and most patterns written. This compresses day 1 to "polish core, add stretch features" instead of "build from zero."
+
+### Week 1: foundations
+
+**By end of week 1:**
+
+- [ ] Get Stable Audio 3 API access / model weights downloaded
+  - [ ] HuggingFace account created
+  - [ ] Request gated access to `stabilityai/stable-audio-3-small`
+  - [ ] Get inference running locally on Vega (or document why cloud-only)
+  - [ ] Time a generation, establish baseline performance
+- [ ] Set up RunPod account (or chosen cloud GPU provider)
+  - [ ] Test deploying a simple inference container
+  - [ ] Verify you can ssh/exec into it
+- [ ] Stand up the repo
+  - [ ] Next.js + TypeScript + Tailwind initialized
+  - [ ] Folder structure per [`02-architecture.md`](02-architecture.md#folder-structure)
+  - [ ] CI with axe-core for accessibility (even on empty pages, it's a foundation)
+  - [ ] Deploy "coming soon" placeholder to Vercel
+- [ ] Set up audio service skeleton
+  - [ ] FastAPI + SA3 inference wrapper
+  - [ ] Single `/generate` endpoint, no LoRA yet
+- [ ] Install NVDA on Windows, run through Reaper once to baseline familiarity
+- [ ] Set up Reaper with a drum sampler VST for testing MIDI export
+
+### Week 2: data and templates
+
+**By end of week 2:**
+
+- [ ] Curate training data for brutal-drum LoRA
+  - [ ] 20–40 one-shots (recordings or sourced, all licensed)
+  - [ ] 10–20 short loops
+  - [ ] Manifest in `data/training/manifest.yaml`
+  - [ ] All preprocessed to 44100 Hz mono
+- [ ] Write the 6 demo-critical pattern templates
+  - [ ] `d-beat.json`
+  - [ ] `blast-traditional.json`
+  - [ ] `skank.json`
+  - [ ] `half-time-metal.json`
+  - [ ] `djent-polyrhythm.json`
+  - [ ] `punk-rock.json`
+- [ ] Write the onomatopoeia mapping table with at least 10 entries
+- [ ] Implement prompt parser MVP (handles the 6 patterns + 10 onomatopoeias)
+- [ ] Implement pattern engine MVP (loads templates, expands to bars, applies tempo)
+- [ ] Implement MIDI generation (downloads work, drags into Reaper)
+
+### Week 3: integration and rehearsal
+
+**By end of week 3:**
+
+- [ ] Train brutal-drum LoRA on cloud GPU
+  - [ ] First attempt: 500 steps, see how it shapes up
+  - [ ] Iterate: adjust learning rate, dataset, prompt format
+  - [ ] Final: ship-ready LoRA + publish to HuggingFace (draft, don't publish yet)
+- [ ] Implement Reaper Web Control client
+  - [ ] Connect, parse state, extract tempo
+  - [ ] Tempo resolution priority implemented
+- [ ] Implement Web Speech API integration
+  - [ ] STT works in Chrome
+  - [ ] TTS works
+  - [ ] Voice state machine (idle → listening → parsing → generating → ready)
+- [ ] Build basic UI shell
+  - [ ] Voice button, transcript display, status panel
+  - [ ] Action buttons (play, download, regenerate)
+  - [ ] Visual grid component (basic version)
+- [ ] Accessibility pass 1
+  - [ ] Tab through every element
+  - [ ] NVDA run-through of the voice flow
+  - [ ] ARIA labels on every interactive element
+  - [ ] Skip links
+  - [ ] High contrast check
+- [ ] End-to-end rehearsal
+  - [ ] Generate a pattern in PatternTalk
+  - [ ] Drag MIDI into Reaper
+  - [ ] Play it
+  - [ ] Generate sample
+  - [ ] Play sample
+  - [ ] Switch on NVDA, redo the flow
+- [ ] Write the team-pitch and post to Music Hackspace Discord
+
+## Hackathon Day 1 (Saturday Aug 22)
+
+### Morning (9:00 AM – 12:30 PM): setup + team formation
+
+- [ ] Arrive at PHI Centre, get settled
+- [ ] Finalize team composition (if recruiting on-site)
+- [ ] Confirm Reaper + PatternTalk working environment
+- [ ] Connect to venue WiFi, verify cloud GPU access
+
+### Early afternoon (12:30 PM – 3:00 PM): core demo path
+
+**Goal:** End-to-end voice → pattern → MIDI → Reaper working.
+
+- [ ] Finalize pattern engine: tempo, bars, time signature, cymbal overrides
+- [ ] Finalize MIDI export, verify it sounds right in Reaper
+- [ ] Wire up Web Speech API end-to-end
+- [ ] Wire up sample generation from cloud GPU
+- [ ] First smoke test: voice prompt → MIDI + sample → download → Reaper
+
+### Late afternoon (3:00 PM – 6:00 PM): variations and audio context
+
+- [ ] Implement 4-variation engine (humanize velocities, micro-timing, fill variants)
+- [ ] Implement uploaded audio BPM detection (Meyda)
+- [ ] Wire up Reaper tempo sync (Web Control client)
+- [ ] Pre-generate demo variations for the showcase patterns
+
+### Evening (6:00 PM – 9:00 PM): polish + accessibility
+
+- [ ] Visual grid component (sighted users)
+- [ ] Pattern library page (skeleton)
+- [ ] Accessibility pass with NVDA
+  - [ ] Tab through everything
+  - [ ] Voice announcements work
+  - [ ] Error states announced
+- [ ] Demo rehearsal (round 1)
+- [ ] Evening check-in / informal demos at the venue
+
+**Day 1 deliverable:** A working PatternTalk that takes voice prompts, generates MIDI, downloads it, and plays in Reaper. Plus 4-variation picker. Plus screenreader-tested.
+
+## Hackathon Day 2 (Sunday Aug 23)
+
+### Morning (9:00 AM – 12:00 PM): stretch features
+
+Priority order (cut from the bottom if time runs short):
+
+1. [ ] **Sample preview player** with progress indicator
+2. [ ] **Pattern library** with search/filter and shareable URLs
+3. [ ] **User-defined onomatopoeias** (localStorage)
+4. [ ] **CLAP plugin wrap** of the web UI (if a teammate can take it)
+5. [ ] **Real-time audio captioning** (stretch, probably cut)
+
+### Midday (12:00 PM – 2:00 PM): polish
+
+- [ ] Final visual grid polish (animations, color tuning)
+- [ ] Voice response tuning (speak rate, prompts)
+- [ ] Pre-generate all demo cache samples
+- [ ] Pre-stage the LoRA weights download for live demo
+- [ ] Test with cloud GPU off (Vega-only path) as fallback
+
+### Afternoon (2:00 PM – 4:00 PM): demo rehearsal
+
+- [ ] Full demo run-through, timed (target: 3–4 minutes)
+- [ ] NVDA demo run-through, timed
+- [ ] VoiceOver demo run-through, timed
+- [ ] Rehearse the pitch (3 sentences max)
+- [ ] Backup plan: video recording of working demo, in case of network issues
+
+### Late afternoon (4:00 PM – 6:00 PM): present
+
+- [ ] Public demos
+- [ ] Jury presentation
+- [ ] Feedback session
+
+### Evening (6:00 PM onwards): wind down
+
+- [ ] Final cleanup
+- [ ] Publish LoRA to HuggingFace (if not already)
+- [ ] Push code to GitHub, write a proper README
+- [ ] Write blog post / social announcement
+
+## Checkpoints
+
+Use these to catch problems early. If a checkpoint fails, stop and address it before moving on.
+
+| Checkpoint | When | What "passing" means |
+|---|---|---|
+| **C1: Inference works** | Pre-hack week 1 | SA3 small generates a sample on Vega in < 10 min OR cloud GPU works |
+| **C2: Training data ready** | Pre-hack week 2 | 30+ samples in `data/training/` with manifest, all licensed |
+| **C3: 6 patterns authored** | Pre-hack week 2 | All 6 demo patterns load, expand, generate MIDI |
+| **C4: End-to-end MIDI** | Pre-hack week 3 | Voice prompt → MIDI → Reaper plays correctly |
+| **C5: NVDA reads the UI** | Pre-hack week 3 | Screenreader announces every state change |
+| **C6: Demo path works** | Hack day 1 | Full voice → MIDI → sample → Reaper in < 60 seconds |
+| **C7: LoRA published** | Hack day 1 evening | Weights on HuggingFace with model card |
+| **C8: Variations work** | Hack day 2 morning | 4 variations show in UI, picker works |
+| **C9: Demo polished** | Hack day 2 afternoon | Rehearsal runs in 3–4 minutes without mistakes |
+
+## What to cut if time runs out
+
+In priority order (drop from the bottom):
+
+1. ❌ Real-time audio captioning
+2. ❌ Haptic metronome PWA
+3. ❌ Reduced-physical-load mode
+4. ❌ CLAP plugin wrap
+5. ❌ User-defined onomatopoeias
+6. ❌ Pattern library page (if a minimal in-app picker works)
+7. ❌ Audio context BPM detection (fall back to prompt/Reaper-only)
+8. ❌ Visual grid polish (fall back to functional ugly grid)
+9. ❌ Dark mode (fall back to light only)
+
+The must-haves are: voice prompt, pattern generation, MIDI export, sample generation, Reaper tempo sync. If we have those five, we have a demo that lands.
+
+## What to add if time is plentiful
+
+In priority order:
+
+1. ✅ CLAP plugin wrap
+2. ✅ Audio context BPM detection
+3. ✅ Pattern library page with shareable URLs
+4. ✅ User-defined onomatopoeias
+5. ✅ Visual grid polish with animations
+6. ✅ Dark mode + theme support
+7. ✅ Multiple LoRA adapters (one per genre: rock, jazz, funk)
+8. ✅ Real-time audio captioning
+
+## Communication cadence
+
+- **Standup** (15 min) at start of each day
+- **Mid-day check-in** (5 min, async) — what's blocked, what's next
+- **End-of-day retro** (15 min) — what shipped, what's deferred
+- **Demo** (3–4 min) at end of each day for informal feedback
+
+## Post-hackathon
+
+**Within 1 week:**
+- [ ] Publish LoRA weights to HuggingFace
+- [ ] Publish repo on GitHub with full README
+- [ ] Blog post / dev.to article about the project
+- [ ] Submit to Music Hackspace showcase if invited
+
+**Within 1 month:**
+- [ ] Add more pattern templates (target: 30+)
+- [ ] Train LoRAs for additional genres
+- [ ] Add CLAP plugin wrap (if not done at hackathon)
+- [ ] Integrate with Narwall for continuous accessibility testing
+
+**Within 3 months:**
+- [ ] Public launch of the web app
+- [ ] Community pattern library with moderation
+- [ ] "Train your own LoRA" UI
+- [ ] Mobile companion app for haptic metronome

docs/09-risks.md

@@ -0,0 +1,314 @@
+# 09 — Risks & Mitigations
+
+Risks ranked by impact × likelihood. Each has an owner, a mitigation, and a contingency.
+
+## Risk matrix
+
+| # | Risk | Likelihood | Impact | Severity | Status |
+|---|---|---|---|---|---|
+| 1 | Cloud GPU unavailable during demo | Low | Critical | **HIGH** | Mitigated |
+| 2 | SA3 inference too slow on Vega | High | High | **HIGH** | Mitigated |
+| 3 | LoRA training fails / produces bad output | Medium | High | **HIGH** | Mitigated |
+| 4 | Voice recognition unreliable in noisy venue | High | Medium | **MEDIUM** | Mitigated |
+| 5 | Reaper Web Control API changes / doesn't work | Medium | Medium | **MEDIUM** | Mitigated |
+| 6 | Pattern templates too few / too low quality | Medium | Medium | **MEDIUM** | Mitigated |
+| 7 | Onomatopoeia parser doesn't understand users | Medium | Low | **MEDIUM** | Mitigated |
+| 8 | Screenreader breaks during demo | Low | Medium | **MEDIUM** | Mitigated |
+| 9 | Network drops during demo | Medium | High | **MEDIUM** | Mitigated |
+| 10 | Solo bottleneck — running out of time | High | High | **HIGH** | Mitigated |
+| 11 | Team conflict / teammate leaves | Medium | High | **MEDIUM** | Monitor |
+| 12 | Licensing issues with training data | Low | High | **MEDIUM** | Mitigated |
+| 13 | Browser doesn't support Web Speech API | Low | High | **MEDIUM** | Mitigated |
+| 14 | MIDI export has bugs that only show in Reaper | Medium | Medium | **MEDIUM** | Mitigated |
+| 15 | Audio sample quality is generic | Medium | Medium | **MEDIUM** | Mitigated |
+
+---
+
+## High-severity risks
+
+### Risk 1: Cloud GPU unavailable during demo
+
+**Scenario:** RunPod has an outage, you can't reach your instance, the venue WiFi blocks the connection, or your account gets suspended.
+
+**Mitigation:**
+- Pre-generate ALL demo samples before the event, store in `cache/` directory
+- Have a backup account on a different provider (Vast.ai + RunPod)
+- Test cloud GPU connection from the venue WiFi before the demo
+
+**Contingency:**
+- Run inference on Vega locally (slow but works)
+- Use pre-generated samples only and label them as "preset variations"
+- Record a video of the working demo as ultimate fallback
+
+**Owner:** You. **Verified:** Test cloud GPU from venue network on day 1 morning.
+
+---
+
+### Risk 2: SA3 inference too slow on Vega
+
+**Scenario:** A 30-second sample takes 15 minutes on your Vega. The demo times out.
+
+**Mitigation:**
+- Establish baseline performance in pre-hack week 1 (see C1 in [`08-build-plan.md`](08-build-plan.md))
+- If > 5 min per sample on Vega, commit to cloud-only
+- Pre-generate demo samples on cloud GPU
+- Cache aggressively (LRU + disk)
+
+**Contingency:**
+- Demo with cached samples only, narrate "this was generated earlier by the model"
+- Show inference happening live as a "by the way, look, it's running" secondary moment, not the main demo
+
+**Owner:** You. **Verified:** Run `scripts/smoke_test.py` on Vega before the event.
+
+---
+
+### Risk 3: LoRA training fails / produces bad output
+
+**Scenario:** Training crashes, or the resulting LoRA makes samples worse than the base model.
+
+**Mitigation:**
+- Run a small training (200 steps) first to verify the pipeline
+- Train the real LoRA at least 3 days before the event, so you have time to iterate
+- Keep the base model as a fallback (can disable LoRA at inference time)
+- Document the training hyperparameters so you can reproduce if needed
+
+**Contingency:**
+- Ship with the base SA3 model only, label output "Stable Audio 3, no fine-tuning"
+- Do a quick second training attempt during the hackathon if you have cloud GPU time
+- Be honest with the jury: "we attempted fine-tuning but the base model worked better for the time we had"
+
+**Owner:** You. **Verified:** Complete first training run before pre-hack week 3.
+
+---
+
+### Risk 10: Solo bottleneck — running out of time
+
+**Scenario:** You try to do everything alone, run out of time, ship a half-finished product.
+
+**Mitigation:**
+- Aggressive scope cut (see [`08-build-plan.md`](08-build-plan.md#what-to-cut-if-time-runs-out))
+- Pre-build as much as possible in the 3 weeks before
+- Define the minimum viable demo path and protect it ruthlessly
+- Daily checkpoint reviews to catch overruns early
+
+**Contingency:**
+- Ship a narrower demo: voice prompt → MIDI export only, no samples
+- Have a video walkthrough of the missing features
+- Focus the live demo on the 2–3 things that work perfectly
+
+**Owner:** You. **Verified:** C6 (demo path works) at end of day 1.
+
+---
+
+## Medium-severity risks
+
+### Risk 4: Voice recognition unreliable in noisy venue
+
+**Scenario:** The hackathon venue is loud. Web Speech API gets garbage transcripts. Demo fails.
+
+**Mitigation:**
+- Use a headset mic / close-mic'd setup, not the laptop mic
+- Test voice recognition in a noisy environment before the event
+- Have a fallback path: type the prompt instead of speaking
+- Push-to-talk (Spacebar to start/stop) avoids picking up ambient noise
+
+**Contingency:**
+- Switch to typed prompts for the demo if voice fails
+- Use a quieter corner of the venue for the live demo
+- Have a backup video of working voice mode recorded in a quiet space
+
+**Owner:** You. **Verified:** Test voice in actual venue conditions.
+
+---
+
+### Risk 5: Reaper Web Control API changes / doesn't work
+
+**Scenario:** Reaper updates, the WebSocket format changes, your client breaks.
+
+**Mitigation:**
+- Test against your installed Reaper version (currently 7.x) before the event
+- Hard-pin the WebSocket protocol version in your client
+- Have the fallback path: "type the BPM manually"
+
+**Contingency:**
+- Demo without Reaper integration, just type the BPM
+- Show Reaper integration in a video if live fails
+
+**Owner:** You. **Verified:** Test on your Reaper install before the event.
+
+---
+
+### Risk 6: Pattern templates too few / too low quality
+
+**Scenario:** You write 5 patterns, all of them are slightly wrong. Jury asks for a beat you don't have.
+
+**Mitigation:**
+- Aim for 18–20 patterns before hackathon
+- Write the 6 demo-critical ones first
+- Each pattern tested in Reaper before the event
+- Have a "blank bar" fallback that lets the user define their own
+
+**Contingency:**
+- Generate variations from existing patterns (different bars, different cymbals, half-time)
+- Be honest: "we focused on metal first, here's what we have"
+
+**Owner:** You. **Verified:** C3 (6 patterns authored) at end of week 2.
+
+---
+
+### Risk 7: Onomatopoeia parser doesn't understand users
+
+**Scenario:** User says "tupatupatupa" but the parser doesn't recognize it. Falls back to genre vocabulary, picks the wrong pattern.
+
+**Mitigation:**
+- Curate the onomatopoeia table with multiple variants per pattern
+- Phonetic matching with Levenshtein distance
+- Confidence threshold (0.7) below which the parser asks for confirmation
+- "I heard X, did you mean Y?" response
+
+**Contingency:**
+- The user can always type the pattern name explicitly
+- "Try one of these patterns: [list]" response
+
+**Owner:** You. **Verified:** Test the top 20 onomatopoeia phrases manually.
+
+---
+
+### Risk 8: Screenreader breaks during demo
+
+**Scenario:** NVDA crashes, VoiceOver doesn't pick up the UI, the screenreader demo fails.
+
+**Mitigation:**
+- Test NVDA + Chrome on the demo machine before the event
+- Have a backup screenreader (VoiceOver on Mac, JAWS if you have access)
+- Record the screenreader demo as a backup video
+- Rehearse the keyboard navigation by feel, not by sight
+
+**Contingency:**
+- Show the recorded video of the working screenreader demo
+- Skip the live screenreader demo, focus on the voice mode
+- Describe the accessibility features narratively
+
+**Owner:** You. **Verified:** Test on the demo machine, not your dev machine.
+
+---
+
+### Risk 9: Network drops during demo
+
+**Scenario:** Venue WiFi dies, you can't reach the cloud GPU for inference.
+
+**Mitigation:**
+- Pre-generate all demo samples, store locally
+- Run a local copy of the audio service on the demo machine as backup
+- Have a mobile hotspot as tertiary fallback
+
+**Contingency:**
+- Demo with cached samples only
+- Acknowledge the network issue honestly if it comes up
+
+**Owner:** You. **Verified:** Confirm cloud GPU + local backup both reachable from venue.
+
+---
+
+### Risk 11: Team conflict / teammate leaves
+
+**Scenario:** A teammate you recruited flakes, or there's conflict about direction.
+
+**Mitigation:**
+- Have all critical code paths owned by you as backup
+- Set clear expectations early (what's the demo, what's the deadline)
+- Communicate scope cuts in real time
+
+**Contingency:**
+- Cut features the flaky teammate was working on
+- Lean on the must-haves list
+
+**Owner:** You. **Status:** Monitor.
+
+---
+
+### Risk 12: Licensing issues with training data
+
+**Scenario:** A sample you used is actually copyrighted, you get called out, model card needs to be pulled.
+
+**Mitigation:**
+- Every sample has a documented source and license in the manifest
+- Prefer CC0 / CC-BY / original recordings
+- For Freesound samples, filter to CC0 or CC-BY only, document the user
+- For your own recordings, document date and context
+
+**Contingency:**
+- If a license is questioned, replace that sample and retrain (time permitting)
+- Be transparent in the model card about licensing discipline
+
+**Owner:** You. **Verified:** Manifest reviewed before publishing.
+
+---
+
+### Risk 13: Browser doesn't support Web Speech API
+
+**Scenario:** Demo machine has Firefox, Web Speech API doesn't work.
+
+**Mitigation:**
+- Test on the demo browser before the event
+- Chrome is the assumption — install it on the demo machine
+
+**Contingency:**
+- Switch to typed prompts only
+- Use a different laptop with Chrome
+
+**Owner:** You. **Verified:** Test on demo browser.
+
+---
+
+### Risk 14: MIDI export has bugs that only show in Reaper
+
+**Scenario:** MIDI plays wrong in Reaper, or doesn't import at all.
+
+**Mitigation:**
+- Test every pattern in Reaper before the event
+- Use a known-good GM drum map
+- Set tempo in the MIDI file header to match project tempo
+- Test on the actual Reaper version you'll use at the event
+
+**Contingency:**
+- Fix the bug live (if quick)
+- Show the MIDI in a different DAW if Reaper is broken
+- Generate a Reaper project file (.rpp) that includes the MIDI in a known-good arrangement
+
+**Owner:** You. **Verified:** Full end-to-end test in Reaper.
+
+---
+
+### Risk 15: Audio sample quality is generic
+
+**Scenario:** Even with the LoRA, the samples sound like generic AI drums, not brutal.
+
+**Mitigation:**
+- Iterate on the training dataset (more samples, better curation)
+- Iterate on prompt engineering (try different intensity descriptors)
+- Generate multiple variations and pick the best
+
+**Contingency:**
+- Show the variations, frame as "exploring the space"
+- Be honest: "SA3 with our LoRA is good but not perfect yet — here's what it produces"
+
+**Owner:** You. **Verified:** Listen to samples before the event.
+
+---
+
+## Risk ownership summary
+
+| Owner | Risks |
+|---|---|
+| You (all) | All risks by default |
+| Future teammate (frontend) | R10 (solo bottleneck) — if recruited |
+| Future teammate (ML) | R3 (LoRA), R2 (Vega speed) — if recruited |
+
+## What we're explicitly NOT risking
+
+- Building features that won't be demoed
+- Custom DAW plugins (too risky for the timeframe)
+- Mobile apps
+- Cloud accounts / user authentication
+- Anything that requires a third-party API key beyond SA3

docs/10-team-pitch.md

@@ -0,0 +1,239 @@
+# 10 — Team Pitch & Skills Needed
+
+## The pitch (post this to Discord)
+
+> Hey — I'm building **PatternTalk** for the Stability AI challenge at the Montreal Music Hackathon (Aug 22–23). The pitch: every existing DAW plugin is a black box to blind and visually impaired producers, and AI music tools completely lack genre expertise — try getting Stable Audio 3 to make a brutal china crash or a d-beat loop and you'll see what I mean. So I'm building two things in one product: (1) a voice-first, screenreader-native interface ("tupatupatupa on the hihat, 4 bars") that produces downloadable MIDI, generated samples via Stable Audio 3, and a screenreader-friendly description of what's being played; (2) a brutal-drum LoRA fine-tune of Stable Audio 3 so the model actually understands the genre. The whole thing is screenreader-native because I'm using a real screenreader throughout development — same approach I use at my day job running [Narwall.tech](https://narwall.tech), an accessibility testing tool. Looking for 1–2 teammates to make this a real demo, not a slideshow. DMs open.
+
+## Skills we're looking for
+
+### Priority 1: Frontend engineer (1 person, ideal)
+
+**What they'd own:**
+- The voice-first UI (Web Speech API, voice state machine)
+- The visual grid component
+- Pattern library page
+- Accessibility implementation (ARIA, keyboard nav, screenreader testing)
+- Deploy to Vercel
+
+**Must-have:**
+- Strong React/Next.js + TypeScript
+- Comfortable with TailwindCSS or similar
+- Cares about accessibility (ideally has shipped accessible UIs)
+- Available for the full hackathon weekend (Aug 22–23 in Montreal)
+
+**Nice-to-have:**
+- Has used Web Speech API before
+- Familiar with @tonejs/midi or Web Audio API
+- Has worked with a screenreader (NVDA, VoiceOver, JAWS)
+- Drummer or musician (genuine interest in the domain, not required)
+
+**Time commitment:**
+- 3 weeks of light prep (a few hours/week to align on architecture)
+- Full weekend in Montreal, Aug 22–23
+
+---
+
+### Priority 2: ML / audio engineer (1 person, *this is the harder one to fill*)
+
+**What they'd own:**
+- Stable Audio 3 inference server (FastAPI + Python)
+- LoRA fine-tuning pipeline
+- Cloud GPU orchestration (RunPod / Vast.ai)
+- Publishing the LoRA weights to HuggingFace
+
+**Must-have:**
+- Comfortable with PyTorch
+- Has fine-tuned diffusion models before (audio models a strong plus)
+- Can deploy Python services (FastAPI, Docker)
+- Available for the full hackathon weekend
+
+**Nice-to-have:**
+- Has specifically worked with Stable Audio, AudioLDM, MusicGen, or Riffusion
+- Has trained LoRAs before
+- Familiar with ROCm or cloud GPU providers
+- Has worked with audio data (sample rates, normalization, etc.)
+
+**Time commitment:**
+- 3 weeks of prep (more than frontend — needs to establish the SA3 pipeline)
+- Full weekend in Montreal, Aug 22–23
+
+---
+
+### Priority 3: Musician / sound designer (optional but valuable)
+
+**What they'd own:**
+- Curate the brutal-drum training dataset
+- Review generated samples for "does this actually sound brutal"
+- Help write pattern templates if you want to delegate some
+- Provide creative direction during the demo
+
+**Must-have:**
+- Plays drums (or has deep familiarity with drumming)
+- Has strong taste in metal/rock/punk
+- Available for the full hackathon weekend
+
+**Nice-to-have:**
+- Produces records or has production experience
+- Has sample library curation experience
+- Has experience with AI music tools (knows what works and what doesn't)
+
+**Time commitment:**
+- Light prep (curate some samples, share references)
+- Full weekend in Montreal, Aug 22–23
+- *Could be remote for prep, in-person for the hackathon*
+
+---
+
+### Priority 4: Designer (optional)
+
+**What they'd own:**
+- Visual grid polish (animations, color tuning)
+- Logo, demo assets, brand if there's time
+- Possibly the marketing visuals for the post-hack blog post
+
+**Must-have:**
+- Visual design sense, especially for accessibility-conscious design
+- Available for at least hackathon day 2
+
+**Nice-to-have:**
+- Has designed for music applications before
+- Has designed with WCAG AA+ compliance in mind
+
+**Time commitment:**
+- Hackathon weekend only is fine
+- Lower priority than engineers
+
+---
+
+## What you (the founder) bring
+
+To attract good teammates, you need to offer something back. Here's what you bring:
+
+**Credibility:**
+- Active startup ([Narwall.tech](https://narwall.tech)) — this isn't a fantasy project
+- Real screenreader testing practice — unique in the music-tech space
+- Drummer + producer with metal bands — domain expertise, no faking needed
+- Working Stable Audio 3 setup planned (or in progress)
+
+**Preparation:**
+- Complete design docs before the event (this directory!)
+- Working code skeleton before the event
+- Pre-curated training dataset
+- Pre-trained LoRA (or first attempt done)
+
+**Project clarity:**
+- A real plan with checkpoints (see [`08-build-plan.md`](08-build-plan.md))
+- A real architecture (see [`02-architecture.md`](02-architecture.md))
+- Honest risk assessment (see [`09-risks.md`](09-risks.md))
+- Scope discipline (clear must-haves vs stretch)
+
+**The pitch itself** — voice-first AI drummer for metal that works with a screenreader — is distinctive enough that good engineers will be interested.
+
+---
+
+## Where to find teammates
+
+### Music Hackspace channels (primary)
+
+1. **Music Hackspace Discord** — main hub, post the pitch there
+   - Invite link on musichackspace.org
+   - Active community of music tech builders
+2. **Prep calls** (Wed evenings, July 29 – Aug 19)
+   - Show up to all of them
+   - Mention you're looking for teammates
+   - This is literally what the prep calls are for
+3. **Montreal music tech community**
+   - If you can attend any in person before the event, do it
+
+### Other channels (secondary)
+
+4. **MUTEK Discord / community** — overlap with hackathon attendees
+5. **Reddit:**
+   - r/WeAreTheMusicMakers
+   - r/musicproduction
+   - r/Drumming
+   - r/musictech
+6. **HuggingFace Discord** — for the ML engineer specifically
+7. **Reaper forums** — for Reaper integration expertise
+8. **Local university CS / music tech programs** (McGill, Concordia in Montreal)
+
+### What to avoid
+
+- Cold-DM-ing strangers without context
+- Promising ownership or revenue (this is a hackathon, set expectations clearly)
+- Recruiting people who don't have the full weekend available
+- Recruiting people who can't be in Montreal in person (remote-only is hard for a hackathon)
+
+---
+
+## How to evaluate candidates
+
+When someone responds to the pitch, ask:
+
+1. **"Can you be in Montreal August 22–23?"** (eliminates 50% of replies)
+2. **"What's the most interesting thing you've built recently?"** (gauge depth)
+3. **"Have you worked with screenreaders before?"** (for frontend; "have you fine-tuned audio models?" for ML)
+4. **"How do you feel about working from a detailed plan rather than improvising?"** (sets expectations)
+5. **"What would you want to own in this project?"** (alignment check)
+
+If they pass those, share the docs (this directory), give them 24 hours to read, then have a 30-minute call to align.
+
+---
+
+## Team formation timeline
+
+| Date | Action |
+|---|---|
+| Now (3 weeks out) | Post pitch to Discord + Reddit |
+| July 29 | Attend prep call #1, mention looking for teammates |
+| Aug 1 | Follow up with interested candidates |
+| Aug 5 | Attend prep call #2, share progress, recruit more |
+| Aug 8 | Finalize team composition |
+| Aug 12 | Attend prep call #3 (with team if formed) |
+| Aug 19 | Attend prep call #4 (final pre-hack alignment) |
+| Aug 22 | Hackathon day 1 |
+
+---
+
+## What if you can't find teammates
+
+Solo is a valid path. The plan is designed to be solo-shippable, with cuts clearly defined.
+
+**If solo:**
+- Focus ruthlessly on the must-haves (voice prompt, MIDI export, sample generation, Reaper sync)
+- Pre-build as much as possible in the 3 weeks
+- Use pre-generated samples and pre-cached variations for the demo
+- Be honest with the jury about the scope
+
+**If you find one teammate (frontend):**
+- You own audio service + training data + LoRA + Reaper integration
+- They own web app + voice UI + visual grid + accessibility
+- This is the ideal 2-person team
+
+**If you find two teammates (frontend + ML):**
+- You own: prompt parser, pattern engine, training data curation, demo, project lead
+- Frontend: web app, voice UI, accessibility
+- ML: audio service, LoRA training, cloud GPU
+- This is the dream team — you have time for stretch features
+
+**If you find a musician-only team:**
+- Less ideal — you'd be doing all the code
+- But the musician adds value on the training data curation and the demo
+
+---
+
+## Post-hackathon: what happens to the team?
+
+This is a hackathon, not a startup. After Aug 23, the team disbands by default. If people want to keep building:
+
+- **You** (the founder) own the IP per the hackathon rules
+- Contributors retain credit in the README and commit history
+- Open-source repo means anyone can fork and continue
+- If the project gains traction, consider:
+  - Adding collaborators as maintainers
+  - Forming a small LLC or collective if commercializing
+  - Or just letting it be an open-source project
+
+Set these expectations at the start: "we own what we build, you get credit, and we can decide post-event whether to continue together."
+
+The Music Hackspace IP rules are explicit: *"Your team keeps 100% ownership of what you create during the hackathon."*

docs/CONTRIBUTING.md

@@ -0,0 +1,160 @@
+# Contributing
+
+## Code of conduct
+
+Be kind. Accessibility-first means inclusive by default. See [the hackathon's CoC](https://musichackspace.org) for the baseline.
+
+## Repo conventions
+
+### Languages
+
+- **TypeScript** for the web app (`apps/web/`)
+- **Python 3.10+** for the audio service (`services/audio/`)
+- **JSON** for pattern templates and onomatopoeia tables
+- **YAML** for training data manifests
+
+### Style
+
+**TypeScript:**
+- ESLint with `@typescript-eslint/recommended`
+- Prettier for formatting
+- No `any` unless absolutely necessary (and then comment why)
+- Functional components, hooks, no class components
+- Avoid `useEffect` for derived state — use `useMemo` or compute inline
+
+**Python:**
+- `ruff` for linting (replaces flake8, isort, etc.)
+- `black` for formatting
+- Type hints everywhere
+- Pydantic for data models
+
+### Naming
+
+- Components: `PascalCase.tsx`
+- Hooks: `useCamelCase.ts`
+- Utilities: `camelCase.ts`
+- Constants: `UPPER_SNAKE_CASE`
+- Files match exports (one default export per file preferred)
+
+### Git
+
+**Commit format** (Conventional Commits):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+Types:
+- `feat` — new feature
+- `fix` — bug fix
+- `docs` — documentation only
+- `style` — formatting, no code change
+- `refactor` — code change that neither fixes a bug nor adds a feature
+- `perf` — performance improvement
+- `test` — adding or fixing tests
+- `chore` — build, CI, tooling
+
+Examples:
+```
+feat(parser): add onomatopoeia matcher with confidence scoring
+fix(midi): correct GM drum map for china (should be 52, was 49)
+docs(architecture): clarify Reaper integration is not a plugin
+chore(ci): add axe-core to GitHub Actions
+```
+
+**Branch naming:**
+- `feat/<short-description>`
+- `fix/<short-description>`
+- `docs/<short-description>`
+- `chore/<short-description>`
+
+Examples:
+- `feat/voice-stt`
+- `fix/midi-tempo-header`
+- `docs/architecture-update`
+
+### Pull requests
+
+- One feature per PR
+- PR description explains *what* and *why*
+- Screenshots / screen recordings for UI changes
+- Accessibility check included (NVDA test notes, axe-core results)
+- All CI checks passing
+
+### Accessibility requirements for every PR
+
+If your PR touches the UI:
+
+- [ ] Run axe-core locally (`npm run test:a11y`) — no AA violations
+- [ ] Tab through the changed flow, verify focus order
+- [ ] Test with NVDA (or document why you couldn't)
+- [ ] All interactive elements have ARIA labels
+- [ ] Color contrast meets WCAG AA (4.5:1 for normal text, 3:1 for large)
+- [ ] No information conveyed by color alone
+
+If your PR is docs-only or backend-only, skip these.
+
+## Adding a new pattern template
+
+1. Create `apps/web/data/patterns/<pattern-id>.json`
+2. Follow the schema in [`03-data-model.md`](03-data-model.md#pattern-templates)
+3. Test in the web app: `npm run dev`, load the pattern, generate MIDI, drag into Reaper
+4. Verify the description reads naturally with a screenreader
+5. Update the pattern list in [`03-data-model.md`](03-data-model.md#pattern-library--starting-list) if adding to the starting list
+
+## Adding a new onomatopoeia
+
+1. Edit `apps/web/data/onomatopoeia.json`
+2. Add the entry with `patterns` (array of variants), `patternId`, and any defaults
+3. Test the phonetic matcher: `npm run test:onomatopoeia`
+4. Manually speak the variants, verify they map correctly
+
+## Adding training data
+
+1. Place audio in `data/training/oneshots/` or `data/training/loops/`
+2. Preprocess: 44100 Hz mono, normalized to -14 LUFS
+3. Add an entry to `data/training/manifest.yaml` with:
+   - `id`, `path`, `category`, `tags`
+   - `source`, `license`, `duration_seconds`
+   - `bpm` (for loops only)
+4. Run `python services/audio/training/preprocess.py` to regenerate the preprocessed versions
+5. Verify the file plays correctly and the license is documented
+
+## Accessibility testing protocol
+
+Before opening a PR that touches UI:
+
+1. **axe-core:** `npm run test:a11y` — must pass with no violations
+2. **NVDA (Windows + Chrome/Firefox):**
+   - Tab through the entire flow
+   - Verify every state change is announced
+   - Verify focus never disappears
+   - Verify error states are announced
+3. **VoiceOver (macOS + Safari):**
+   - Repeat the NVDA flow
+   - Especially test the grid navigation with VO + arrow keys
+4. **Keyboard-only:**
+   - Complete the entire demo flow without using the mouse
+   - Verify every action has a keyboard equivalent
+5. **High contrast:**
+   - Enable Windows High Contrast Mode
+   - Verify the UI is still usable
+6. **200% zoom:**
+   - Zoom the browser to 200%
+   - Verify no content is cut off or unreachable
+
+If any of these fail, the PR is not ready.
+
+## Communication
+
+- **Issues** — use GitHub Issues for bugs, feature requests, design questions
+- **Discussions** — use GitHub Discussions for broader questions
+- **Discord** — for real-time chat during the hackathon
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the project's MIT license (code) or CC-BY (sample data where applicable).

docs/HANDOFF.md

@@ -0,0 +1,144 @@
+# HANDOFF — stable-jam resume guide
+
+> This file exists so a fresh session can `cd D:/CODE/stable-jam` and pick up
+> exactly where the previous one left off — no loss of context. Read this first,
+> then the linked docs.
+
+**Product:** Jam Buddy (consolidated here as **stable-jam**). "You start playing,
+it joins in." A call-and-response AI music companion using Stable Audio 3,
+built for the Stability AI Challenge at Music Hackspace Montreal (Aug 22–23 2026).
+
+---
+
+## What this repo is (and is not)
+
+`stable-jam/` is the **source + docs + tests** for the Jam Buddy product. It does
+NOT contain the heavy vendored model repos — those stay in the previous
+location and are referenced by env vars (below). Don't expect to `git clone` and
+get a GPU model; the SA3 weights are a separate download.
+
+**Copied from** `D:/CODE/unstable-drums/` (the previous working dir, still intact
+if you need to recover anything). This dir was created to give the hackathon a
+clean, product-accurate home.
+
+## Product state (what actually works, verified this session)
+
+- **Web app** (`apps/web`): hardware-sampler rack UI. Instrument pads (bass/lead/
+  rhythm/synth/drums), Genre/Mood/Tempo knobs, a "Your take" section with BOTH a
+  MIDI file input and an audio file input, JOIN IN + PLAY BOTH buttons, status
+  panel (aria-live) showing "Buddy tempo: N BPM", and an audio player. Every
+  response is saved to `generations/` at the repo root.
+- **SA3 pipeline** (`tools/jam_buddy.py`): the CLI that does the generation.
+  Two input modes:
+  - `--midi take.mid` — detects tempo (exact) + response length from the take,
+    generates a complementary melodic part at that tempo. **Ignores the groove**
+    (SA3 can't parse MIDI notes).
+  - `--wav take.wav` — TRUE audio-to-audio via `init_audio` + `init_noise_level`
+    (default 0.4). The buddy actually HEARS the groove and responds rhythmically.
+  - `--bpm N` / `--model small-music|small-sfx` / `--genre` / `--duration`.
+  - Drums force `small-sfx` (clean isolated hits); everything else `small-music`.
+- **API route** (`apps/web/app/api/jambuddy/route.ts`): POST /api/jambuddy with
+  `{knobs, bpm?, midi?, audio?, duration?}`, shells to the python, returns the
+  WAV + `X-Jam-Buddy-BPM` header. Writes output to `<repo>/generations/`.
+- **Prompt builder** (`apps/web/lib/jambuddy/prompt.ts`): pure function building
+  the SA3 prompt from the knobs per the official SA3 prompting guide
+  (TrackType: Instrument, instrument, genre, mood, BPM, studio recording).
+  Negative prompt steers away from a full mix. `MODEL_FOR_INSTRUMENT` maps
+  drums→small-sfx.
+- **Player** (`apps/web/lib/jambuddy/player.ts`): browser Web Audio. `playTogether`
+  renders the MIDI take as oscillators and plays it with the buddy WAV on the
+  same clock. **Note: this was "banked" — the user reported PLAY BOTH only
+  played the generated part, not the MIDI synth. It's parked, not debugged.**
+
+## Verified this session (proof)
+
+- Web: `pnpm run test` -> 31/31 pass (prompt, player, engine, conversation);
+  `tsc --noEmit` clean; page serves the rack.
+- CLI: `jam_buddy.py --midi <file>` -> detected 158 BPM, 24.3s response matching
+  the take. Audio-to-audio on a 5s take -> ~10s wall, valid WAV (peak 0.43,
+  rms 0.08). A ~378s take times out on CPU — keep audio takes short.
+- The generations dir fills with timestamped WAVs.
+
+## Key environment / paths
+
+SA3 (the engine) now lives IN this repo at `stable-audio-3/`. The venv's
+editable-install `.pth` was repointed to this location (was `D:/CODE/unstable-drums/...`).
+The `/api/jambuddy` route auto-resolves it via `join(repoRoot, "stable-audio-3", ...)`.
+
+| Var | Value |
+|---|---|
+| `JAM_BUDDY_ROOT` | `D:/CODE/stable-jam` (repo root; route walks up to find `tools/jam_buddy.py`) |
+| `JAM_BUDDY_PYTHON` | `D:/CODE/stable-jam/stable-audio-3/.venv/Scripts/python.exe` (the SA3 venv) |
+| SA3 weights | cached in `stable-audio-3/.venv` + HF cache on G:/AI/models/huggingface |
+| `HF_TOKEN` | in old repo's `.env` (needed for gated SA3 model access) — copy if regenerating weights |
+
+The SA3 venv was extended with `mido` and `librosa`
+(`uv pip install --python .../stable-audio-3/.venv/Scripts/python.exe mido librosa`).
+A fresh session must use that venv or recreate it.
+
+## How to run (fresh session)
+
+```bash
+cd D:/CODE/stable-jam
+# 1. install web deps (node_modules was NOT copied)
+cd apps/web && pnpm install && cd ../..
+
+# 2. run tests + typecheck
+cd apps/web && npx vitest run && npx tsc --noEmit
+
+# 3. dev server
+cd apps/web && pnpm dev   # -> http://localhost:3000
+
+# 4. python pipeline (SA3 venv is in THIS repo)
+./stable-audio-3/.venv/Scripts/python.exe tools/jam_buddy.py --midi take.mid --instrument bass --out out.wav
+```
+
+## Docs (all in `docs/`)
+
+- `01-vision.md` — Jam Buddy vision (rewritten from the old PatternTalk framing).
+- `02-architecture.md` — note: may still describe the old service layout; the
+  real arch is: Next.js web + `tools/jam_buddy.py` + SA3 venv.
+- `05-accessibility.md` — the a11y strategy (still relevant; the product is
+  screenreader-compatible by design).
+- `06-stable-audio-integration.md` — SA3 setup, audio-to-audio, Vega notes.
+- `HARNESS.md` — agent harness commands + test contract (may still say
+  "PatternTalk" in places; the real product is Jam Buddy).
+
+## What's deliberately NOT in this repo (and why)
+
+- `text2midi/` (2.8G vendored model) — not part of the Jam Buddy product; it
+  stays in the previous working dir if needed.
+- The SA3 weights / `.venv` are inside `stable-audio-3/` here but **gitignored**
+  (large, regenerable, license-gated). See `.gitignore`.
+- `node_modules/`, `.next/` — regenerable, not committed.
+- `generations/*.wav` — gitignored (regenerable output).
+- Source song/GP files + scratch WAVs in the old `tools/` — not product source.
+
+## Pending / next steps (from the last session)
+
+1. **PLAY BOTH** — unbank / fix: the MIDI synth part wasn't audible. Likely the
+   object URL or the oscillator gain. That's the "co-play" wow moment.
+2. **Metadata sidecar** — add a `<file>.json` next to each `generations/*.wav`
+   with prompt / negative / model / BPM / duration / source. Answers "what did it
+   go off on."
+3. **Re-render the docs** `02-architecture.md`, `03-data-model.md`,
+   `04-ux-voice-first.md`, `07-reaper-integration.md` to match Jam Buddy (they
+   still describe the old PatternTalk drum-machine in places).
+4. **LoRA / underfit** (style trainer) is a real path but needs a GPU — not shipped.
+5. **Demo script** — the judge's-eye review (session bg_161745) recommended a
+   3-min demo script; see `docs/01-vision.md` "What success looks like".
+
+## The judge's review (session `bg_161745` — hackathon judge design review)
+
+Key finding: **docs and product were telling different stories** (PatternTalk vs
+Jam Buddy). That's why this repo was consolidated to `stable-jam`. Scoring
+rubric + recs live in that session. The #1 fix was "kill the PatternTalk framing"
+— largely done in README + 01-vision; the deeper docs still need the same pass.
+
+## The SA3 tempo/time-signature reality (don't re-learn it)
+
+Stable Audio 3 has NO tempo or time-signature conditioning channel. "BPM" is a
+weak semantic hint in the prompt. So "make SA3 follow a time signature" is not
+possible with the stock model. The answer is MIDI-first (timing from MIDI/audio
+detection) + SA3 as the timbre generator. Full reasoning is in the skill ref
+`sa3-no-tempo-control.md`. The LoRA style path is separate.

docs/HARNESS.md

@@ -0,0 +1,55 @@
+# stable-jam — Agent Harness
+
+**Jam Buddy** — "you start playing, it joins in." An AI music companion for the
+**Music Hackspace Montreal** hackathon (Aug 22–23, 2026, Stability AI challenge).
+A Next.js web rack + a Python SA3 pipeline that listens to a MIDI or audio take
+and responds at your tempo in the instrument you pick.
+
+## Roles
+
+- **Web app** — `apps/web/` (Next.js + TS + Tailwind + Vitest). The hardware
+  sampler rack: instrument pads, genre/mood/tempo knobs, MIDI/audio take input,
+  JOIN IN + PLAY BOTH, status panel, and `generations/` output.
+- **SA3 pipeline** — `tools/jam_buddy.py` (Python). Detects tempo + duration
+  from a MIDI take (or runs audio-to-audio from a WAV), builds the SA3 prompt
+  from the knobs, generates the response WAV via the `stable-audio-3` venv.
+- **Prompt builder** — `apps/web/lib/jambuddy/prompt.ts` (pure, tested).
+- **Player** — `apps/web/lib/jambuddy/player.ts` (Web Audio; play take + buddy
+  together). Note: PLAY BOTH is banked / not fully debugged.
+- **Legacy converters** — `gp5_to_keyswitched_mid.py` / `midi_to_gp5.py` /
+  `midjson_to_mid.py` (GP5↔MIDI tooling from the earlier iteration, still present).
+
+## Commands
+
+```bash
+# Web app (node_modules NOT committed — install first)
+cd apps/web && pnpm install && npx vitest run      # 31 tests
+cd apps/web && npx tsc --noEmit                     # typecheck
+pnpm dev                                            # local Next.js server -> :3000
+
+# Python pipeline (SA3 venv is in THIS repo)
+./stable-audio-3/.venv/Scripts/python.exe tools/jam_buddy.py --midi take.mid --instrument bass --out out.wav
+
+# Conversion CLIs (if needed)
+python gp5_to_keyswitched_mid.py path/to/song.gp5
+```
+
+## Test contract
+
+- Web: `apps/web/__tests__/` — `prompt.test.ts` (prompt builder),
+  `player.test.ts` (midi parsing/player), `engine.test.ts`, `conversation.test.ts`.
+- Python: `tests/` — GP5 conversion against `tests/expected/baseline.yaml`.
+
+## Conventions
+
+- TS for web, Python 3.10+ for audio/conversion.
+- Accessibility-first (screenreader-native): axe-core, NVDA + VoiceOver checks.
+- Conventional Commits, `feat/*`/`fix/*`/`docs/*`/`chore/*` branches.
+
+## Not-in-git (deliberately)
+
+- `stable-audio-3/` + `text2midi/` (vendored models) live in the previous dir;
+  referenced via `JAM_BUDDY_PYTHON`. Don't copy them into this repo.
+- `node_modules/`, `.next/`, `generations/*.wav` — regenerable.
+
+See `docs/HANDOFF.md` for the full resume guide and current product state.

gp5_to_keyswitched_mid.py

@@ -0,0 +1,1123 @@
+#!/usr/bin/env python3
+"""
+Guitar Pro 5 (.gp5) -> Sforzando Keyswitched MIDI Converter
+============================================================
+
+Reads a .gp5 file, detects common guitar articulations (palm mute, staccato,
+harmonic, slide, bend) on every note of every guitar track, and emits a Type 1
+MIDI file with the corresponding Sforzando keyswitch notes inserted exactly one
+tick before each articulated note.
+
+Bass tracks are skipped by default. Pass --include-bass to also process them.
+
+All guitar tracks of the same instrument kind (e.g. two rhythm guitars) are
+merged into a single MIDI track on a single channel, so Sforzando receives a
+clean instrument-shaped stream.
+
+INSTALL
+-------
+    pip install PyGuitarPro mido
+
+USAGE
+-----
+    python gp5_to_keyswitched_mid.py path/to/song.gp5
+    python gp5_to_keyswitched_mid.py path/to/song.gp5 output.mid
+    python gp5_to_keyswitched_mid.py song.gp5 -b           # also process bass
+    python gp5_to_keyswitched_mid.py song.gp5 -V 100 -r   # velocity 100, emit sustain reset
+
+Edit the KEYSWITCH_MAP dictionary below to change the keyswitch note numbers
+to match the keyswitches declared in your .sfz instrument.
+"""
+
+import argparse
+import os
+import re
+import sys
+
+import guitarpro
+import mido
+
+
+__all__ = [
+    "KEYSWITCH_MAP",
+    "INCLUDE_BASS",
+    "MERGE_BY_INSTRUMENT",
+    "EMIT_SUSTAIN_RESET",
+    "SUSTAIN_KEYSWITCH",
+    "DEFAULT_VELOCITY",
+    "detect_techniques",
+    "convert",
+    "main",
+]
+
+
+# ---------------------------------------------------------------------------
+# EDITABLE SETTINGS
+# ---------------------------------------------------------------------------
+
+# Map detected technique name -> Sforzando keyswitch MIDI note number.
+# THIS IS A TEMPLATE. The actual keyswitch numbers depend on the SFZ
+# instrument you load in Sforzando. Verify each value by:
+#   1. Open the .sfz file in a text editor.
+#   2. Search for the technique name (e.g. 'sustain', 'palm_mute').
+#   3. Find the sw_lokey/sw_hikey range that selects it; the keyswitch
+#      note is the value inside that range.
+#   4. Or just play the note in Sforzando and listen.
+# Below is one plausible mapping for Unreal Instruments METAL-GTX, based
+# on the reabank metadata in the .sfz. Treat it as a starting point, not
+# a guarantee. You can override at the CLI with --keyswitch-map FILE.
+#   sustain   F1  / 17   — Sustain Down
+#   palm_mute G#1 / 20   — Palm Mute Down
+#   slide     C1  / 24   — Slide Up
+#   harmonic  A0  /  9   — Natural Harmonics
+#   bend      G6  / 91   — Bending semi
+# Staccato is intentionally NOT mapped: on a real guitar it is a
+# duration/timing property, not a separate articulation. The original
+# note's envelope is preserved by NOT emitting a staccato key.
+KEYSWITCH_MAP = {
+    "sustain":        17,
+    "palm_mute":      20,
+    "harmonic":        9,
+    "slide_up":       24,
+    "slide_down":     23,
+    "slide_in":       27,
+    "hammer":         26,
+    "bend":           91,
+}
+
+# The keyswitch note number used to (re)assert the sustain/clean state.
+# SusUp (F#0 = 18) is the cleaner-sounding of the two sustain keys in
+# METAL-GTX — SusDown (F0 = 17) has a noticeable palm-mute-like quality.
+# When a note in the GP file has no articulation, the script emits this
+# key at the same tick so the sampler always knows what to play.
+SUSTAIN_KEYSWITCH = 18
+
+# Length of a keyswitch note (in ticks, at 960 PPQ). 960 ticks = one quarter
+# note, which is large enough to be visible in any DAW's piano roll and
+# long enough that no host will drop it. The actual delivered duration is
+# further clamped to the gap until the next event on the same channel so
+# two consecutive keyswitches never overlap.
+KEYSWITCH_DURATION_TICKS = 960
+
+# MIDI note numbers used as keyswitches. Used to truncate each keyswitch
+# note_off to the gap before the next event on the same channel.
+
+# General MIDI drum programs. A track is treated as drums if it uses one of
+# these programs on a non-channel-9 channel, OR if its name says "drum".
+_GM_DRUM_PROGRAMS = set(range(8, 17))  # 8..16 (drums 8..15 + reverse cymbal 16)
+
+# General MIDI guitar programs (24..31 cover acoustic/electric/clean/distortion/
+# overdriven/lead/etc., plus the muted guitar 28 and overdriven 29).
+_GM_GUITAR_PROGRAMS = set(range(24, 32))
+
+# General MIDI bass programs (32..39).
+_GM_BASS_PROGRAMS = set(range(32, 40))
+
+_GUITAR_NAME_TOKENS = (
+    "guitar", "rhythm", "lead", "clean", "harmony", "distort",
+)
+_BASS_NAME_TOKENS = (
+    "bass", "fretless", "slap",
+)
+_DRUM_NAME_TOKENS = (
+    "drum", "kit", "percussion",
+)
+
+# Program numbers that, when seen alone, are ambiguous (e.g. program 0 =
+# "Acoustic Grand Piano" in GM, but GP5 also uses 0 for drums when the
+# channel is 9). The classifier consults the track name in that case.
+
+# Process bass tracks too. Override at the CLI with --include-bass.
+INCLUDE_BASS = False
+
+# When False (default), every included GP track becomes its own output MIDI
+# track on its own channel, the channel the track had in the Guitar Pro file.
+# This is the right mode for selecting a single track by name (--only) and
+# for the common case of driving several Sforzando instances at once.
+# Set to True to merge tracks of the same instrument kind into one MIDI
+# track on a single deterministic channel.
+MERGE_BY_INSTRUMENT = False
+
+# When True (default), every non-articulated note in the GP file emits a
+# sustain key (SUSTAIN_KEYSWITCH) at the same tick. This guarantees the
+# sampler is always in a known state, regardless of what the previous
+# sample held. Turn off with --no-sustain-reset on the CLI if you want
+# explicit keyswitches only at articulated notes.
+EMIT_SUSTAIN_RESET = True
+
+# When True (default), trim leading silence so the first event lands at
+# tick 0. Empty intro bars in the GP file are removed from the MIDI
+# output. Useful when the GP arrangement has a long count-in or rests
+# before the first note.
+TRIM_SILENCE = True
+
+# Velocity used when a note has no explicit velocity or its value is 0.
+DEFAULT_VELOCITY = 100
+
+
+# ---------------------------------------------------------------------------
+# TRACK CLASSIFICATION
+# ---------------------------------------------------------------------------
+# PyGuitarPro does not always populate `track.instrument.kind`. The reliable
+# signals are: (1) the GM program number on `track.channel` (mute-proof, this
+# is what the .gp5 file actually stores), and (2) the track name. We use
+# both so that contrived tracks ("Julien Bass") are recognised even when the
+# program number happens to be 0.
+
+def _channel_1based(gp_track):
+    """Return the 1-based MIDI channel of a GP track, or None if unknown."""
+    ch = getattr(gp_track, "channel", None)
+    raw = getattr(ch, "channel", None) if ch is not None else None
+    if raw is None:
+        return None
+    return int(raw) + 1  # GP is 0-based, but here we want 1-based for the
+    # common "channel 9 = drums" convention.
+
+def _program_number(gp_track):
+    """Return the GM program number 0-127 for a GP track, or None if unknown."""
+    ch = getattr(gp_track, "channel", None)
+    return getattr(ch, "instrument", None) if ch is not None else None
+
+def _track_name(gp_track):
+    n = getattr(gp_track, "name", None) or ""
+    return n.strip().lower()
+
+def _classify_track(gp_track):
+    """
+    Return (category, kind_label) for a GP track.
+
+    category is one of: 'guitar', 'bass', 'drums', 'other'.
+    kind_label is a short string used for channel hashing (e.g.
+    'electricGuitar', 'fretlessBass').
+    """
+    name = _track_name(gp_track)
+    name_lower = name.lower()
+    chan_1b = _channel_1based(gp_track)
+    prog = _program_number(gp_track)
+
+    # Channel 9 in GP5 is always drums in the files we care about.
+    if chan_1b == 10:
+        return ("drums", "drums")
+
+    # Name-based overrides win early — GP5 files often use inconsistent
+    # program numbers (e.g. program 0 for "Julien Bass") and the name is
+    # the most reliable signal.
+    if any(tok in name_lower for tok in _DRUM_NAME_TOKENS):
+        return ("drums", "drums")
+    if any(tok in name_lower for tok in _BASS_NAME_TOKENS):
+        return ("bass", _classify_bass_label(name, prog))
+    if any(tok in name_lower for tok in _GUITAR_NAME_TOKENS):
+        return ("guitar", _classify_guitar_label(name, prog))
+
+    # Fall back to program number.
+    if prog is not None:
+        if prog in _GM_DRUM_PROGRAMS:
+            return ("drums", "drums")
+        if prog in _GM_BASS_PROGRAMS:
+            return ("bass", _classify_bass_label(name, prog))
+        if prog in _GM_GUITAR_PROGRAMS:
+            return ("guitar", _classify_guitar_label(name, prog))
+
+    return ("other", "other")
+
+
+_GUITAR_PROGRAM_LABEL = {
+    24: "nylonGuitar", 25: "steelGuitar", 26: "jazzGuitar",
+    27: "cleanGuitar", 28: "mutedGuitar", 29: "overdrivenGuitar",
+    30: "distortionGuitar", 31: "harmonicsGuitar",
+}
+_BASS_PROGRAM_LABEL = {
+    32: "acousticBass", 33: "fingeredBass", 34: "pickedBass",
+    35: "fretlessBass", 36: "slapBass1", 37: "slapBass2",
+    38: "synthBass1", 39: "synthBass2",
+}
+
+
+def _classify_guitar_label(name, prog):
+    if prog is not None and prog in _GUITAR_PROGRAM_LABEL:
+        return _GUITAR_PROGRAM_LABEL[prog]
+    # Press fragile names: 'lead' / 'rhythm' / 'clean' / 'harmony' / 'distort'
+    nl = name.lower()
+    for tok in ("lead", "rhythm", "clean", "harmony", "distort", "acoustic"):
+        if tok in nl:
+            return f"{tok}Guitar"
+    return "electricGuitar"
+
+
+def _classify_bass_label(name, prog):
+    if prog is not None and prog in _BASS_PROGRAM_LABEL:
+        return _BASS_PROGRAM_LABEL[prog]
+    return "bassGuitar"
+
+
+# Reserve channel 9 (GM percussion) for drums. Sforzando expects the
+# instrument on a pitched channel.
+_RESERVED_CHANNELS = {9}
+
+
+def _midi_channel_for(kind_name):
+    """
+    Return a deterministic MIDI channel 0-15 for a given instrument kind.
+    Channel 9 is skipped (GM percussion). Identical kind names always resolve
+    to the same channel, so merging tracks of the same kind keeps the
+    resulting overlapping notes on the same channel.
+    """
+    if not kind_name:
+        return 0
+    h = sum(ord(c) for c in kind_name)
+    ch = h % 16
+    if ch in _RESERVED_CHANNELS:
+        ch = (ch + 1) % 16
+    return ch
+
+
+def _bucket_tracks_by_kind(guitar_tracks, bass_included):
+    """
+    Group included tracks into (kind_label, [gp_track, ...]) buckets.
+
+    Guitars are split by their kind label (e.g. 'cleanGuitar' becomes its
+    own bucket), so a file with rhythm + lead + clean guitars gets three
+    separate MIDI tracks. Bass tracks, when included, land in a single
+    'Bass' bucket.
+
+    Returns a list of (bucket_label, kind_name, [gp_track...]) tuples in the
+    order they should appear in the output MIDI.
+    """
+    guitar_buckets = {}
+    for t in guitar_tracks:
+        kind = _classify_track(t)[1]
+        guitar_buckets.setdefault(kind, []).append(t)
+
+    buckets = []
+    for kind in sorted(guitar_buckets):
+        n = len(guitar_buckets[kind])
+        if len(guitar_buckets) == 1 and len(guitar_tracks) > 1:
+            label = "Guitar"
+        elif n == 1:
+            label = f"Guitar: {kind}"
+        else:
+            label = f"Guitar: {kind}"
+        buckets.append((label, kind, guitar_buckets[kind]))
+
+    if bass_included:
+        if len(bass_included) == 1:
+            label = "Bass"
+            kind = _classify_track(bass_included[0])[1]
+        else:
+            kind = _classify_track(bass_included[0])[1]
+            label = f"Bass: {kind}"
+        buckets.append((label, kind, bass_included))
+
+    return buckets
+
+
+# ---------------------------------------------------------------------------
+# FILENAME HELPERS
+# ---------------------------------------------------------------------------
+_FILENAME_FORBIDDEN = re.compile(r"[\\/:\*\?\"<>\|]+")
+_FILENAME_WHITESPACE = re.compile(r"\s+")
+_FILENAME_EDGEPUNCT = "\u2024\u2025\u2026\ufeff. "
+
+
+def _sanitize_filename(name, default="output"):
+    """Make a track name safe for use as a filename on Windows / macOS / Linux."""
+    cleaned = _FILENAME_FORBIDDEN.sub(" ", name or "")
+    cleaned = _FILENAME_WHITESPACE.sub(" ", cleaned).strip()
+    cleaned = cleaned.rstrip(". ")
+    cleaned = cleaned.strip(_FILENAME_EDGEPUNCT)
+    if not cleaned:
+        cleaned = default
+    return cleaned
+
+
+def _song_subfolder(input_path):
+    """
+    Derive a subfolder name from the .gp5 input file. The folder holds
+    per-track MIDI files so exports from different songs don't mix in
+    the same directory.
+    """
+    head, tail = os.path.split(input_path)
+    base, _ = os.path.splitext(tail)
+    return _sanitize_filename(base, default="song")
+
+
+def _auto_output_path(only_filters, input_path, only_index=None):
+    """
+    Build a default output path. Files are organized as
+    <song_subfolder>/<track_name>_keyswitched.mid so exports from
+    different songs don't collide in the same directory.
+
+    Rules:
+    - No --only filter: fall back to <song_subfolder>/output_keyswitched.mid.
+    - --only matches exactly one track (or --only-index picks one):
+        <song_subfolder>/<sanitized_track_name>_keyswitched.mid.
+    - --only matches zero tracks: fall back to the default; the caller
+        will report 'no tracks found' anyway.
+    - --only matches multiple tracks and no --only-index: return None
+        to signal the caller to require an explicit output path.
+    """
+    subfolder = _song_subfolder(input_path)
+    if not only_filters:
+        return os.path.join(subfolder, "output_keyswitched.mid")
+    song = guitarpro.parse(input_path)
+    matched = [t for t in song.tracks
+               if any(f.lower() in _track_name(t) for f in only_filters)]
+    n_matched = len(matched)
+    if only_index is not None:
+        if 1 <= only_index <= n_matched:
+            matched = [matched[only_index - 1]]
+        else:
+            return None
+    if len(matched) == 1:
+        # When --only matched multiple tracks but --only-index picked one,
+        # include the index in the filename so the file is uniquely named.
+        suffix = f" ({only_index})" if only_index is not None and n_matched > 1 else ""
+        return os.path.join(
+            subfolder,
+            f"{_sanitize_filename(matched[0].name)}{suffix}_keyswitched.mid",
+        )
+    if len(matched) == 0:
+        return os.path.join(subfolder, "output_keyswitched.mid")
+    return None  # ambiguous: caller must supply an output path
+
+
+# ---------------------------------------------------------------------------
+# ARTICULATION DETECTION
+# ---------------------------------------------------------------------------
+def detect_techniques(note):
+    """
+    Return a list of (technique_name, params_dict) tuples found on a note.
+
+    The technique name is the key into KEYSWITCH_MAP. A technique that
+    doesn't need to be split (e.g. palm_mute, harmonic) returns an empty
+    params dict. Slides return a 'direction' parameter ('up' or 'down')
+    based on the source pitch versus the next note on the same string.
+    """
+    techniques = []
+    effect = getattr(note, "effect", None)
+    if effect is None:
+        return techniques
+
+    # Palm mute: boolean flag.
+    if getattr(effect, "palmMute", False):
+        techniques.append(("palm_mute", {}))
+
+    # Staccato: boolean flag.
+    if getattr(effect, "staccato", False):
+        techniques.append(("staccato", {}))
+
+    # Harmonic: HarmonicEffect object when present (natural, artificial,
+    # pinch, tap, semi, feedback). We collapse all harmonic flavors to one
+    # 'harmonic' keyswitch; split by effect.harmonic.type if your SFZ needs
+    # finer resolution.
+    if getattr(effect, "harmonic", None) is not None:
+        techniques.append(("harmonic", {}))
+
+    # Hammer-on / pull-off: boolean flag. The METAL-GTX SFZ has a
+    # dedicated Hammer-On patch triggered by keyswitch D1 (MIDI 26).
+    if getattr(effect, "hammer", False):
+        techniques.append(("hammer", {}))
+
+    # Grace notes: stored as a GraceEffect on the note's effect. The
+    # transition field tells us whether the grace slides, hammers, or
+    # bends into the main note. In METAL-GTX, slide-in graces map to
+    # D#1 (MIDI 27) and bend-in graces map to the bend keyswitch.
+    grace = getattr(effect, "grace", None)
+    if grace is not None:
+        transition = getattr(grace, "transition", None)
+        if transition is not None:
+            t_name = getattr(transition, "name", str(transition))
+            if t_name == "slide":
+                techniques.append(("slide_in", {}))
+            elif t_name == "hammer":
+                techniques.append(("hammer", {}))
+            elif t_name == "bend":
+                techniques.append(("bend", {}))
+
+    # Slides: iterable of slide types. Direction is determined by the
+    # caller (see _resolve_slide_direction, which compares the slide
+    # note's pitch to the next note on the same string). If direction
+    # can't be determined, the slide defaults to 'slide_up'.
+    slides = getattr(effect, "slides", None)
+    if slides is not None:
+        try:
+            if len(slides) > 0:
+                techniques.append(("slide", {}))
+        except TypeError:
+            techniques.append(("slide", {}))
+
+    # Bend: BendEffect with a `points` list when present.
+    if getattr(effect, "bend", None) is not None:
+        techniques.append(("bend", {}))
+
+    return techniques
+
+
+def _resolve_slide_direction(note, track_notes, note_index):
+    """
+    Determine whether a slide note goes up or down.
+
+    The PYGuitarPro note carries a slide flag but not the target pitch.
+    The target is the next note (in time) on the same string. The caller
+    passes a flat list of all notes in the track and the current note's
+    index in that list.
+
+    Returns 'up', 'down', or None (when direction cannot be determined).
+    """
+    if note.string is None:
+        return None
+    src_pitch = note.realValue
+    # Look ahead for the next note on the same string.
+    for later in track_notes[note_index + 1:]:
+        if getattr(later, "string", None) == note.string:
+            if later.realValue > src_pitch:
+                return "up"
+            if later.realValue < src_pitch:
+                return "down"
+            return None  # same pitch: ambiguous
+    return None
+
+
+def _expand_slide(tech, params, direction):
+    """
+    Resolve a 'slide' technique into 'slide_up' or 'slide_down' based on
+    the pre-computed direction. For other techniques, return the name
+    unchanged so the keyswitch-map lookup works.
+    """
+    if tech != "slide":
+        return tech
+    if direction == "down":
+        return "slide_down"
+    return "slide_up"  # default + 'up'
+
+
+def _build_tie_chain_map(track):
+    """
+    Walk every note in the track and compute the absolute end-tick of
+    each note's envelope. Tied notes share the same attack as their
+    progenitor, so the progenitor's note_off is set to the end of the
+    last tied continuation. The map is keyed by id(note).
+
+    Returns a dict {id(note): end_tick} where end_tick is the absolute
+    tick at which the note's note_off should fire.
+    """
+    note_end = {}
+    # Walk beats in time order, tracking the most recent non-tied note
+    # on each (string, pitch) pair.
+    active = {}  # (string, pitch) -> id(note)
+    for measure in track.measures:
+        for voice in measure.voices:
+            if voice.isEmpty:
+                continue
+            for beat in voice.beats:
+                beat_start = int(beat.start)
+                beat_dur = int(beat.duration.time)
+                for note in beat.notes:
+                    if note.type == guitarpro.NoteType.dead:
+                        continue
+                    key = (note.string, note.realValue)
+                    note_dur = int(round(beat_dur * float(note.durationPercent)))
+                    if note.type == guitarpro.NoteType.tie:
+                        # Continuation of the active note on this key.
+                        progenitor = active.get(key)
+                        if progenitor is not None:
+                            # Extend the progenitor's end tick.
+                            note_end[progenitor] = beat_start + note_dur
+                        # Note: tied notes themselves don't get their own
+                        # note_on/note_off — they share the attack.
+                    else:
+                        # New attack. Register it as the active note on
+                        # this key, and finalize its end tick (for now).
+                        note_end[id(note)] = beat_start + note_dur
+                        active[key] = id(note)
+    return note_end
+
+
+# ---------------------------------------------------------------------------
+# CONVERSION
+# ---------------------------------------------------------------------------
+def _clamp(value, lo, hi):
+    """Clamp an int-castable value to [lo, hi]."""
+    return max(lo, min(hi, int(value)))
+
+
+def convert(gp5_path, output_path="output_keyswitched.mid",
+            keyswitch_map=None, include_bass=None,
+            emit_sustain_reset=None, trim_silence=None,
+            fallback_velocity=None, only=None, only_index=None, verbose=True):
+    """
+    Parse a Guitar Pro 5 file and write a keyswitched MIDI file.
+
+    Parameters
+    ----------
+    gp5_path : str
+        Path to the .gp5 input file.
+    output_path : str
+        Path for the generated MIDI file. Default: 'output_keyswitched.mid'.
+    keyswitch_map : dict, optional
+        Override the default technique -> keyswitch note mapping.
+    include_bass : bool, optional
+        If True, also process bass tracks. Defaults to INCLUDE_BASS.
+    emit_sustain_reset : bool, optional
+        If True, emit a sustain keyswitch (SUSTAIN_KEYSWITCH) at tick 0 of
+        every processed track. Defaults to EMIT_SUSTAIN_RESET.
+    fallback_velocity : int, optional
+        Velocity used when a note has no explicit velocity. Defaults to
+        DEFAULT_VELOCITY.
+    only : str | iterable[str] | None, optional
+        If given, only GP tracks whose name contains the supplied substring
+        (case-insensitive) are considered. Pass a list for multiple filters.
+    verbose : bool
+        If True, print a summary of which tracks were processed / skipped.
+    """
+    if keyswitch_map is None:
+        keyswitch_map = dict(KEYSWITCH_MAP)
+    if include_bass is None:
+        include_bass = INCLUDE_BASS
+    if emit_sustain_reset is None:
+        emit_sustain_reset = EMIT_SUSTAIN_RESET
+    if trim_silence is None:
+        trim_silence = TRIM_SILENCE
+    if fallback_velocity is None:
+        fallback_velocity = DEFAULT_VELOCITY
+    if only is None:
+        only_filters = None
+    elif isinstance(only, str):
+        only_filters = [only]
+    else:
+        only_filters = list(only)
+    if only_index is None:
+        only_index = None  # explicit
+    # When only_index is used, switch to exact-match filtering so the
+    # picked track is unique (substring match would still match the
+    # other same-named tracks).
+    only_exact = False
+    only_track = None  # pinned track object when only_index is set
+
+    song = guitarpro.parse(gp5_path)
+
+    if only_filters is not None and only_index is not None:
+        matched = [t for t in song.tracks
+                   if any(f.lower() in _track_name(t).lower() for f in only_filters)]
+        if 1 <= only_index <= len(matched):
+            # Pin to a specific track by id() so the partition loop
+            # can match exactly one track (since name-based filters would
+            # still match both same-named tracks).
+            only_filters = None  # disable name filter
+            only_track = matched[only_index - 1]
+        else:
+            print(f"ERROR: --only-index {only_index} out of range "
+                  f"(only {len(matched)} matches found)", file=sys.stderr)
+            return None  # let caller handle ambiguous / out-of-range
+
+    # PyGuitarPro stores timing on the parent beat:
+    #     beat.start        -> absolute tick of the beat
+    #     beat.duration.time -> duration in ticks at 960 PPQ (already
+    #                           accounts for dotted/tuplet)
+    #     note.durationPercent -> how much of the beat the note occupies
+    # The MIDI file uses 960 ticks per beat to match that domain exactly,
+    # so the 1-tick keyswitch offset is preserved precisely.
+    mid = mido.MidiFile(type=1, ticks_per_beat=960)
+
+    # ---- Track 0: conductor (tempo + time signature) --------------------
+    conductor = mid.add_track("Conductor")
+    # mido's set_tempo takes microseconds per quarter note, not BPM.
+    # Guitar Pro stores the song tempo as BPM, so we convert.
+    bpm = int(song.tempo) if getattr(song, "tempo", None) else 120
+    tempo = int(60_000_000 / bpm)
+    conductor.append(mido.MetaMessage("set_tempo", tempo=tempo, time=0))
+
+    if song.tracks and song.tracks[0].measures:
+        first_ts = song.tracks[0].measures[0].timeSignature
+        if first_ts is not None:
+            # `denominator` is a Duration struct whose `.value` is the
+            # actual denominator (4 for quarter, 8 for eighth, 16 for
+            # sixteenth). It is NOT a 2** enum like in some older GP
+            # versions. The MIDI `time_signature` meta uses the same
+            # denominator number directly.
+            actual_denom = int(first_ts.denominator.value)
+            conductor.append(mido.MetaMessage(
+                "time_signature",
+                numerator=int(first_ts.numerator),
+                denominator=actual_denom,
+                time=0,
+            ))
+
+    # ---- Partition tracks: included (guitar / bass) vs. skipped --------
+    included_guitar = []
+    included_bass   = []
+    skipped_tracks  = []
+    for gp_track in song.tracks:
+        name = _track_name(gp_track)
+        raw_name = getattr(gp_track, "name", None) or ""
+        if only_track is not None:
+            # Only the pinned track passes.
+            if gp_track is not only_track:
+                skipped_tracks.append(gp_track)
+                continue
+        elif only_filters is not None:
+            if only_exact:
+                # Match against the raw (case-preserving) track name.
+                if raw_name not in only_filters:
+                    skipped_tracks.append(gp_track)
+                    continue
+            else:
+                if not any(f.lower() in name for f in only_filters):
+                    skipped_tracks.append(gp_track)
+                    continue
+        category, _kind = _classify_track(gp_track)
+        if category == "guitar":
+            included_guitar.append(gp_track)
+        elif category == "bass" and include_bass:
+            included_bass.append(gp_track)
+        else:
+            skipped_tracks.append(gp_track)
+
+    if MERGE_BY_INSTRUMENT:
+        buckets = _bucket_tracks_by_kind(included_guitar, included_bass)
+    else:
+        # One output MIDI track per GP track. The channel the track had
+        # in the .gp5 file is preserved on the message events; the MIDI
+        # track itself is named after the GP track.
+        buckets = []
+        for t in included_guitar + included_bass:
+            ch_obj = getattr(t, "channel", None)
+            raw_ch = getattr(ch_obj, "channel", None)
+            channel = int(raw_ch) if raw_ch is not None else 0
+            if channel == 9:  # never reuse GM percussion
+                channel = 0
+            label = t.name or "Guitar"
+            buckets.append((label, f"track:{label}", [t]))
+
+    if not buckets:
+        if verbose:
+            print("No guitar"
+                  + ("/bass" if include_bass else "")
+                  + " tracks found in this file.")
+        parent = os.path.dirname(output_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        mid.save(output_path)
+        return output_path
+
+    # ---- Per-bucket processing ----------------------------------------
+    # Each bucket produces exactly one MIDI track on a single channel.
+    # Notes from multiple GP tracks within a bucket are merged in absolute
+    # tick space, then sorted, so the 1-tick-before keyswitch relationship
+    # is preserved across tracks.
+    written_buckets = []
+    for bucket_idx, (label, kind_name, tracks) in enumerate(buckets, start=1):
+        if MERGE_BY_INSTRUMENT:
+            channel = _midi_channel_for(kind_name)
+        else:
+            # When unmerged, the channel is the GP track's own channel so
+            # the output matches how the track was originally authored.
+            ch_obj = getattr(tracks[0], "channel", None)
+            raw_ch = getattr(ch_obj, "channel", None)
+            channel = int(raw_ch) if raw_ch is not None else 0
+            if channel == 9:
+                channel = 0
+
+        # Collect (absolute_tick, mido.Message) pairs for this bucket.
+        events = []
+        # Set of (tick, channel) where a default sustain key has already
+        # been queued for this bucket. Prevents one sustain key per
+        # note in a chord (e.g. notes 50, 45, 38 at one tick emit a
+        # single sustain key, not three).
+        pending_default_sustain = set()
+
+        for gp_track in tracks:
+            # Pre-collect every note in the track in time order. After
+            # the full list is built, compute slide direction for each
+            # note that has a slide — direction is determined by comparing
+            # the slide note's pitch to the next note on the same string
+            # (the slide target).
+            track_notes = []
+            for measure in gp_track.measures:
+                for voice in measure.voices:
+                    if voice.isEmpty:
+                        continue
+                    for beat in voice.beats:
+                        for note in beat.notes:
+                            track_notes.append(note)
+            slide_direction = {}
+            for idx, note in enumerate(track_notes):
+                if getattr(note.effect, "slides", None):
+                    slide_direction[id(note)] = _resolve_slide_direction(
+                        note, track_notes, idx)
+            # Pre-compute the end-tick of every note's envelope, taking
+            # tied continuations into account. Without this, a note with
+            # tied continuations gets its note_off at the end of the
+            # first beat, cutting the tail short.
+            note_end = _build_tie_chain_map(gp_track)
+
+            for measure in gp_track.measures:
+                for voice in measure.voices:
+                    if voice.isEmpty:
+                        continue
+                    for beat in voice.beats:
+                        for note in beat.notes:
+                            # Tied continuations do not replay a pitched
+                            # note (they share the previous attack's
+                            # envelope), but they CAN carry new
+                            # articulations — e.g. a tied note with a
+                            # bend means the bend starts on the tied
+                            # side, not the original attack. Emit
+                            # keyswitches for tied notes with techniques,
+                            # but skip the pitched note_on/note_off.
+                            if note.type == guitarpro.NoteType.dead:
+                                continue
+                            tied_loud = (note.type == guitarpro.NoteType.tie)
+                            techniques_early = []
+                            if tied_loud:
+                                techniques_early = [
+                                    (t, p) for (t, p) in detect_techniques(note)
+                                    if keyswitch_map.get(_expand_slide(t, p, slide_direction.get(id(note)))) is not None
+                                ]
+                                if not techniques_early:
+                                    continue
+                                # Fall through: emit keyswitches only.
+
+                            # Timing lives on the beat; the note can only
+                            # shorten its slot (durationPercent). When the
+                            # note has a tied continuation, the note_end
+                            # map gives the absolute end-tick of the
+                            # entire tie chain (the note's envelope
+                            # extends through all tied continuations).
+                            start    = int(beat.start)
+                            note_end_tick = note_end.get(id(note))
+                            if note_end_tick is not None:
+                                duration = note_end_tick - start
+                            else:
+                                duration = int(round(beat.duration.time
+                                                     * float(note.durationPercent)))
+                            if duration < 1:
+                                duration = 1
+                            pitch    = _clamp(note.realValue, 0, 127)
+
+                            velocity = int(getattr(note, "velocity", 0) or 0)
+                            if velocity < 1:
+                                velocity = fallback_velocity
+                            velocity = _clamp(velocity, 1, 127)
+
+                            # ---- Emit explicit keyswitches per note ----
+                            # Every note gets an explicit keyswitch(es)
+                            # at `start` (the SAME tick as the pitched
+                            # note's note_on). The keyswitch is appended
+                            # to the event list BEFORE the pitched note_on,
+                            # so within the same tick it arrives first in
+                            # the MIDI stream — Sforzando accepts this
+                            # and behaves identically to a 1-tick-before
+                            # trigger. The natural off time is start +
+                            # KEYSWITCH_DURATION_TICKS (a quarter note so
+                            # it shows up in the DAW piano roll), then a
+                            # later post-process pass clamps it to the
+                            # next event on the same channel so two
+                            # consecutive keyswitches never overlap.
+                            #
+                            # If the note has no articulation (e.g. a
+                            # clean chord) AND the user has enabled
+                            # EMIT_SUSTAIN_RESET, tag this note as
+                            # 'default-sustain-candidate'. Per-tick, we
+                            # emit a single default sustain key on the
+                            # first such note — this guarantees the sampler
+                            # is always in a known state, regardless of
+                            # what the previous sample held (which fixes
+                            # the common case where a palm-mute figure
+                            # ends and the next clean chord is played in
+                            # the wrong still-palm-muted state), and
+                            # avoids duplicate sustain keys on chords.
+                            techniques = detect_techniques(note)
+                            if any(ks_notes_emitted for _ in []):  # placeholder
+                                pass
+                            ks_notes_emitted = []
+                            has_articulation = False
+                            for tech, params in techniques:
+                                if tech == "slide":
+                                    direction = slide_direction.get(id(note))
+                                    tech = "slide_down" if direction == "down" else "slide_up"
+                                ks_note = keyswitch_map.get(tech)
+                                if ks_note is None:
+                                    continue
+                                if ks_note == 26:
+                                    import sys as _sys
+                                ks_note = _clamp(ks_note, 0, 127)
+                                ks_notes_emitted.append(ks_note)
+                                has_articulation = True
+
+                            if not has_articulation and emit_sustain_reset:
+                                # Defer: emit one default sustain per
+                                # (tick, channel) below, after the loop.
+                                if (start, channel) not in pending_default_sustain:
+                                    pending_default_sustain.add((start, channel))
+                                    ks_notes_emitted.append(_clamp(SUSTAIN_KEYSWITCH, 0, 127))
+
+                            for ks_note in ks_notes_emitted:
+                                ks_on   = start
+                                ks_off  = ks_on + KEYSWITCH_DURATION_TICKS
+                                events.append((
+                                    ks_on,
+                                    mido.Message("note_on",  channel=channel,
+                                                 note=ks_note, velocity=velocity,
+                                                 time=0),
+                                ))
+                                events.append((
+                                    ks_off,
+                                    ("keyswitch_off", ks_note, channel),
+                                ))
+
+                            # ---- The actual pitched note --------------
+                            # Skip note_on/note_off for tied notes (the
+                            # pitch is already sounding from the
+                            # original attack).
+                            if not tied_loud:
+                                events.append((
+                                    start,
+                                    mido.Message("note_on",  channel=channel,
+                                                 note=pitch, velocity=velocity,
+                                                 time=0),
+                                ))
+                                events.append((
+                                    start + duration,
+                                    mido.Message("note_off", channel=channel,
+                                                 note=pitch, velocity=0,
+                                                 time=0),
+                                ))
+        if not events:
+            if verbose:
+                print(f"  [{bucket_idx}] {label}: no notes, skipping")
+            continue
+
+        # ---- Resolve keyswitch_off placeholders into real note_off ----
+        # ---- messages with clamped ticks. Three constraints:         ----
+        # ---- 1. keyswitch note_off must arrive at or before           ----
+        # ----    key_on_tick + KEYSWITCH_DURATION_TICKS               ----
+        # ---- 2. successive keyswitch note_on on the same channel/note-
+        # ----    is treated as a re-trigger: the previous key closes   ----
+        # ----    *at the tick of the next note_on* and a new key opens. -
+        # ---- 3. Any non-sentinel note_on / note_off on the same       ----
+        # ----    channel/note also closes the open key (same as 2).    ----
+        keyswitch_notes = {v for v in KEYSWITCH_MAP.values() if v is not None}
+        keyswitch_notes.add(SUSTAIN_KEYSWITCH)
+        import sys as _sys
+        n26_post_loop = sum(1 for t, p in events
+                            if hasattr(p, 'note') and p.note == 26
+                            and p.type == 'note_on' and getattr(p, 'velocity', 0) > 0)
+        events.sort(key=lambda e: e[0])
+
+        # DEBUG: count 26 in events
+        n26 = sum(1 for t, p in events
+                  if hasattr(p, 'note') and p.note == 26
+                  and p.type == 'note_on' and getattr(p, 'velocity', 0) > 0)
+        n26_tup = sum(1 for t, p in events
+                      if isinstance(p, tuple) and p[0] == 'keyswitch_off' and p[1] == 26)
+        if n26 > 0:
+            pass
+        def _close_oldest_open(ch, note, at_tick, out):
+            stack = open_keyswitch_stacks.get((ch, note))
+            if not stack:
+                return
+            ks_on = stack.pop(0)
+            if not open_keyswitch_stacks[(ch, note)]:
+                del open_keyswitch_stacks[(ch, note)]
+            cap = ks_on + KEYSWITCH_DURATION_TICKS
+            clamped = min(at_tick, cap)
+            if clamped < ks_on:
+                clamped = ks_on
+            out.append((clamped, mido.Message(
+                "note_off", channel=ch, note=note, velocity=0, time=0)))
+
+        resolved = []
+        open_keyswitch_stacks = {}
+        for tick, payload in events:
+            if isinstance(payload, tuple) and payload and payload[0] == "keyswitch_off":
+                _, ks_note, ch = payload
+                _close_oldest_open(ch, ks_note, tick, resolved)
+            elif isinstance(payload, mido.Message) and payload.type == "note_on" \
+                    and payload.note in keyswitch_notes:
+                # Close any still-open key on the same channel/note at
+                # this tick (re-trigger semantics).
+                _close_oldest_open(payload.channel, payload.note, tick, resolved)
+                resolved.append((tick, payload))
+                open_keyswitch_stacks.setdefault(
+                    (payload.channel, payload.note), []).append(tick)
+            elif isinstance(payload, mido.Message) and payload.type == "note_off" \
+                    and payload.note in keyswitch_notes:
+                # An explicit note_off from the emitter (e.g. the user
+                # inserted one) closes the open key.
+                _close_oldest_open(payload.channel, payload.note, tick, resolved)
+            else:
+                resolved.append((tick, payload))
+        events = resolved
+
+        midi_track = mid.add_track(label)
+        last_tick  = 0
+        for abs_tick, msg in events:
+            msg.time  = max(0, abs_tick - last_tick)
+            last_tick = abs_tick
+            midi_track.append(msg)
+
+        written_buckets.append((label, kind_name, len(tracks), channel))
+
+    # ---- Trim leading silence -------------------------------------------
+    # If the user asked for trim_silence, find the earliest absolute tick
+    # across all tracks and shift every event so the first one lands at
+    # tick 0. This removes empty intro bars.
+    if trim_silence:
+        earliest = None
+        for tr in mid.tracks:
+            abs_t = 0
+            for msg in tr:
+                abs_t += msg.time
+                if isinstance(msg, mido.MetaMessage) and msg.type == "time_signature":
+                    if abs_t > 0 and (earliest is None or abs_t < earliest):
+                        earliest = abs_t
+                if isinstance(msg, mido.Message) and msg.type in (
+                        "note_on", "note_off"):
+                    if earliest is None or abs_t < earliest:
+                        earliest = abs_t
+        if earliest is not None and earliest > 0:
+            for tr in mid.tracks:
+                # Walk events, accumulate times, rewrite each with the
+                # shift. Events that fall before the earliest tick are
+                # dropped or kept at time 0 (meta only).
+                rebuilt = []
+                abs_t = 0
+                first_real_done = False
+                for msg in tr:
+                    new_abs = abs_t - earliest
+                    abs_t += msg.time
+                    if new_abs < 0:
+                        # Drop note events; keep meta (set_tempo, track_name,
+                        # time_signature, end_of_track) at time 0. Use
+                        # copy(time=0) to preserve the original meta values.
+                        if isinstance(msg, mido.MetaMessage):
+                            rebuilt.append(msg.copy(time=0))
+                        continue
+                    # Update the delta time so the event lands at new_abs.
+                    if not first_real_done:
+                        msg.time = new_abs
+                        first_real_done = True
+                    rebuilt.append(msg)
+                tr.clear()
+                for m in rebuilt:
+                    tr.append(m)
+    parent = os.path.dirname(output_path)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    mid.save(output_path)
+
+    # ---- Summary --------------------------------------------------------
+    if verbose:
+        for label, kind_name, n_gp, channel in written_buckets:
+            if n_gp == 1:
+                print(f"  {label}  [{kind_name}]  channel {channel}")
+            else:
+                print(f"  {label}  [{kind_name}]  channel {channel}  "
+                      f"(merged {n_gp} GP tracks)")
+        if skipped_tracks:
+            print(f"Skipped {len(skipped_tracks)} other track(s):")
+            for t in skipped_tracks:
+                category, kind = _classify_track(t)
+                print(f"      - {t.name or '(unnamed)'}  "
+                      f"[{kind} -> {category}]")
+
+    return output_path
+
+
+# ---------------------------------------------------------------------------
+# CLI ENTRY POINT
+# ---------------------------------------------------------------------------
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="gp5_to_keyswitched_mid",
+        description=(
+            "Convert a Guitar Pro 5 file to a Sforzando keyswitched MIDI. "
+            "Only guitar tracks are processed by default; pass --include-bass "
+            "to also process bass tracks."
+        ),
+    )
+    parser.add_argument("input",
+                        help="Path to the input .gp5 file")
+    parser.add_argument("output",
+                        nargs="?",
+                        default=None,
+                        help="Path for the output MIDI file. If omitted, the "
+                             "tool derives a name from the GP track name "
+                             "when --only matches one track; otherwise it "
+                             "uses 'output_keyswitched.mid'.")
+    parser.add_argument("-b", "--include-bass",
+                        action="store_true",
+                        help="Also process bass tracks (skipped by default).")
+    parser.add_argument("-V", "--velocity",
+                        type=int,
+                        default=DEFAULT_VELOCITY,
+                        help="Fallback velocity 1-127 for notes missing one "
+                             "(default: %(default)s).")
+    parser.add_argument("-R", "--no-sustain-reset",
+                        action="store_true",
+                        help="Do NOT emit a sustain key on every non-"
+                             "articulated note. By default, every note "
+                             "without an articulation carries a sustain "
+                             "key so the sampler is always in a known "
+                             "state (no stale palm-mute bleeding into "
+                             "clean chords).")
+    parser.add_argument("-q", "--quiet",
+                        action="store_true",
+                        help="Suppress the per-track summary.")
+    parser.add_argument("-o", "--only",
+                        action="append",
+                        default=None,
+                        help="Only process GP tracks whose name contains this "
+                             "substring (case-insensitive). Repeat for "
+                             "multiple names, e.g. -o Roberto -o DANY.")
+    parser.add_argument("-T", "--no-trim-silence",
+                        action="store_true",
+                        help="Do NOT trim leading silence. By default the "
+                             "first event lands at tick 0, so empty intro "
+                             "bars from the GP file are removed from the "
+                             "MIDI output.")
+    parser.add_argument("--only-index", type=int, default=None,
+                        help="When --only matches multiple tracks, pick "
+                             "the Nth (1-based) match. Useful when several "
+                             "tracks share a name.")
+    args = parser.parse_args(argv)
+
+    # Resolve output path: explicit > auto-derived from --only > default.
+    if args.output is None:
+        args.output = _auto_output_path(args.only, args.input, only_index=args.only_index)
+        if args.output is None:
+            print("ERROR: --only matched multiple tracks; please supply an "
+                  "explicit output path or use --only-index to disambiguate.",
+                  file=sys.stderr)
+            return 4
+
+    try:
+        result = convert(
+            args.input,
+            args.output,
+            include_bass=args.include_bass,
+            emit_sustain_reset=not args.no_sustain_reset,
+            trim_silence=not args.no_trim_silence,
+            fallback_velocity=args.velocity,
+            only=args.only,
+            only_index=args.only_index,
+            verbose=not args.quiet,
+        )
+    except FileNotFoundError:
+        print(f"ERROR: input file not found: {args.input}", file=sys.stderr)
+        return 2
+    except Exception as exc:  # noqa: BLE001
+        print(f"ERROR: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 3
+
+    if result is None:
+        # convert() couldn't resolve the track selection.
+        return 4
+
+    print(f"OK: wrote {result}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gp_to_keyswitched_mid.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * gp_to_keyswitched_mid.js
+ * ========================
+ * Convert a Guitar Pro 7/8 (.gp) file to per-track Sforzando keyswitched MIDI.
+ *
+ * PyGuitarPro only reads up to GP5, so this uses alphaTab (which reads GP7/8
+ * .gp natively) to extract notes + articulations in absolute-tick space, then
+ * emits a JSON event stream that a tiny mido-based writer turns into a Type-1
+ * MIDI file. The keyswitch mapping and sustain-reset behaviour mirror
+ * gp5_to_keyswitched_mid.py exactly so both tools produce compatible output.
+ *
+ * INSTALL
+ *     npm install @coderline/alphatab   (in this directory)
+ *
+ * USAGE
+ *     node gp_to_keyswitched_mid.js <input.gp> <out_dir> [--include-drums]
+ *         [--no-sustain-reset] [--no-trim-silence] [--velocity N]
+ *
+ * One <TrackName>_keyswitched.mid is written per non-drum track into <out_dir>.
+ * Tracks that share a name get a "(N)" suffix so files never collide.
+ *
+ * The script prints a JSON object to stdout that the配套 Python writer
+ * consumes; humans can read the per-track summary at the bottom of the output.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const at = require('@coderline/alphatab');
+
+// ---- keyswitch map (same as gp5_to_keyswitched_mid.py) ---------------------
+const KEYSWITCH_MAP = {
+    sustain:   17,
+    palm_mute: 20,
+    harmonic:  9,
+    slide_up:  24,
+    slide_down: 23,
+    slide_in:  27,
+    hammer:    26,
+    bend:      91,
+};
+const SUSTAIN_KEYSWITCH = 18;       // SusUp (cleaner sustain)
+const KEYSWITCH_DURATION_TICKS = 960; // one quarter, clamped later
+const DEFAULT_VELOCITY = 100;
+
+// alphaTab Dynamics enum -> MIDI velocity
+// Off=0, ppp=1, pp=2, p=3, mp=4, mf=5, f=6, ff=7, fff=8
+const DYN_VEL = { 1: 16, 2: 32, 3: 48, 4: 64, 5: 80, 6: 96, 7: 112, 8: 127 };
+
+const args = process.argv.slice(2);
+if (args.length < 2) {
+    console.error('Usage: node gp_to_keyswitched_mid.js <input.gp> <out_dir> [options]');
+    process.exit(1);
+}
+const inputPath = args[0];
+const outDir = args[1];
+const opts = {
+    includeDrums: args.includes('--include-drums'),
+    sustainReset: !args.includes('--no-sustain-reset'),
+    trimSilence: !args.includes('--no-trim-silence'),
+    fallbackVel: parseInt(args.find((a, i) => args[i - 1] === '--velocity')) || DEFAULT_VELOCITY,
+};
+
+function clamp(v, lo, hi) { return Math.max(lo, Math.min(hi, v | 0)); }
+
+function loadScore(file) {
+    const bytes = fs.readFileSync(file);
+    return at.importer.ScoreLoader.loadScoreFromBytes(bytes, new at.Settings());
+}
+
+function isDrumTrack(t) {
+    if (t.isPercussionTrack) return true;
+    const pi = t.playbackInfo || {};
+    if (pi.primaryChannel === 9) return true;
+    return /drum|kit|percussion/i.test(t.name || '');
+}
+
+function velocityFor(note, beat) {
+    const d = note.dynamics ?? beat.dynamics;
+    if (d && DYN_VEL[d]) return DYN_VEL[d];
+    return opts.fallbackVel;
+}
+
+// --- articulation detection -------------------------------------------------
+function detectTechniques(note, beat) {
+    const techs = [];
+    if (note.isPalmMute || beat.isPalmMute) techs.push('palm_mute');
+    if (note.harmonicType) techs.push('harmonic');
+    if (note.isHammerPullOrigin) techs.push('hammer');
+    if (note.slideInType) techs.push('slide_in');
+    // slides out / to a target -> directional slide
+    if (note.slideOutType || note.slideTarget) {
+        let dir = 'up';
+        if (note.slideTarget) {
+            dir = note.slideTarget.realValue > note.realValue ? 'up' :
+                 note.slideTarget.realValue < note.realValue ? 'down' : 'up';
+        } else if (note.slideOutType === 2) dir = 'down';
+        techs.push(dir === 'down' ? 'slide_down' : 'slide_up');
+    }
+    if (note.bendType || (note.bendPoints && note.bendPoints.length)) techs.push('bend');
+    return techs;
+}
+
+// --- tie-chain end-tick map -------------------------------------------------
+// Mirrors _build_tie_chain_map from the GP5 tool: the origin note's note_off
+// extends through every tied continuation on the same (string, pitch).
+function buildNoteEndMap(track, absStartOf) {
+    const noteEnd = new Map(); // id(note) -> absolute end tick
+    const active = new Map();  // "string|pitch" -> id(origin note)
+    for (const st of track.staves) {
+        for (let bi = 0; bi < st.bars.length; bi++) {
+            const bar = st.bars[bi];
+            const barStart = absStartOf(bar);
+            for (const voice of bar.voices) {
+                if (voice.isEmpty) continue;
+                for (const beat of voice.beats) {
+                    const start = barStart + (beat.playbackStart || 0);
+                    const dur = beat.playbackDuration || 0;
+                    for (const note of beat.notes) {
+                        if (note.isDead) continue;
+                        const key = note.string + '|' + note.realValue;
+                        const nd = Math.max(1, Math.round(dur * (note.durationPercent || 1)));
+                        if (note.isTieDestination) {
+                            const origin = active.get(key);
+                            if (origin !== undefined) noteEnd.set(origin, start + nd);
+                            // tied notes don't get their own note_on/off
+                        } else {
+                            noteEnd.set(note.id, start + nd);
+                            active.set(key, note.id);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return noteEnd;
+}
+
+function buildTrackEvents(track, absStartOf) {
+    const channel = (track.playbackInfo && track.playbackInfo.primaryChannel != null)
+        ? track.playbackInfo.primaryChannel : 0;
+    const ch = channel === 9 ? 0 : channel; // never reuse GM percussion
+
+    const noteEnd = buildNoteEndMap(track, absStartOf);
+
+    // raw events: { tick, kind:'note_on'|'note_off', note, velocity, ks?:bool }
+    const events = [];
+    const pendingSustain = new Set(); // "tick" -> already emitted sustain at this tick
+
+    for (const st of track.staves) {
+        for (let bi = 0; bi < st.bars.length; bi++) {
+            const bar = st.bars[bi];
+            const barStart = absStartOf(bar);
+            for (const voice of bar.voices) {
+                if (voice.isEmpty) continue;
+                for (const beat of voice.beats) {
+                    const start = barStart + (beat.playbackStart || 0);
+                    for (const note of beat.notes) {
+                        if (note.isDead) continue;
+                        const tied = note.isTieDestination;
+                        const techs = detectTechniques(note, beat);
+                        const ksNotes = [];
+                        let hasArticulation = false;
+                        for (const t of techs) {
+                            const ks = KEYSWITCH_MAP[t];
+                            if (ks != null) { ksNotes.push(ks); hasArticulation = true; }
+                        }
+                        // Tied notes share the previous attack's envelope. They only
+                        // emit keyswitches when they carry a NEW articulation (e.g. a
+                        // bend starting on the tied side). A tied note with no
+                        // articulation emits nothing — no default sustain either.
+                        if (!tied && !hasArticulation && opts.sustainReset) {
+                            if (!pendingSustain.has(start)) {
+                                pendingSustain.add(start);
+                                ksNotes.push(SUSTAIN_KEYSWITCH);
+                            }
+                        }
+                        const vel = clamp(velocityFor(note, beat), 1, 127);
+                        for (const ks of ksNotes) {
+                            events.push({ tick: start, kind: 'note_on', note: ks, velocity: vel, ks: true });
+                            // sentinel: close at start+DUR (clamped later)
+                            events.push({ tick: start + KEYSWITCH_DURATION_TICKS, kind: 'keyswitch_off', note: ks, velocity: 0, ks: true });
+                        }
+                        if (!tied) {
+                            const end = noteEnd.has(note.id) ? noteEnd.get(note.id) : (start + Math.max(1, Math.round((beat.playbackDuration || 0) * (note.durationPercent || 1))));
+                            const pitch = clamp(note.realValue, 0, 127);
+                            events.push({ tick: start, kind: 'note_on', note: pitch, velocity: vel, ks: false });
+                            events.push({ tick: end, kind: 'note_off', note: pitch, velocity: 0, ks: false });
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    if (!events.length) return null;
+
+    // --- clamp keyswitch_off + re-trigger (mirrors the GP5 tool) ------------
+    const ksSet = new Set(Object.values(KEYSWITCH_MAP));
+    ksSet.add(SUSTAIN_KEYSWITCH);
+    events.sort((a, b) => a.tick - b.tick);
+
+    const openStacks = new Map(); // "ch|note" -> [onTick,...]
+    const resolved = [];
+    function closeOldest(ch, note, atTick) {
+        const key = ch + '|' + note;
+        const stack = openStacks.get(key);
+        if (!stack || !stack.length) return;
+        const onTick = stack.shift();
+        if (!stack.length) openStacks.delete(key);
+        const cap = onTick + KEYSWITCH_DURATION_TICKS;
+        let clamped = Math.min(atTick, cap);
+        if (clamped < onTick) clamped = onTick;
+        resolved.push({ tick: clamped, kind: 'note_off', note, velocity: 0, ks: true });
+    }
+    for (const e of events) {
+        if (e.kind === 'keyswitch_off') {
+            closeOldest(ch, e.note, e.tick);
+        } else if (e.kind === 'note_on' && e.ks && ksSet.has(e.note)) {
+            closeOldest(ch, e.note, e.tick); // re-trigger closes previous
+            resolved.push(e);
+            const key = ch + '|' + e.note;
+            if (!openStacks.has(key)) openStacks.set(key, []);
+            openStacks.get(key).push(e.tick);
+        } else if (e.kind === 'note_off' && e.ks && ksSet.has(e.note)) {
+            closeOldest(ch, e.note, e.tick);
+        } else {
+            resolved.push(e);
+        }
+    }
+    let out = resolved;
+
+    // --- trim leading silence ---------------------------------------------
+    if (opts.trimSilence) {
+        let earliest = null;
+        for (const e of out) {
+            if (e.kind === 'note_on' || e.kind === 'note_off') {
+                if (earliest === null || e.tick < earliest) earliest = e.tick;
+            }
+        }
+        if (earliest != null && earliest > 0) {
+            out = out
+                .filter(e => e.tick - earliest >= 0)
+                .map(e => ({ ...e, tick: e.tick - earliest }));
+        }
+    }
+    out.sort((a, b) => a.tick - b.tick);
+    return { name: track.name || 'Guitar', channel: ch, events: out };
+}
+
+function main() {
+    const score = loadScore(inputPath);
+    const mbStart = new Map(); // bar.index -> start tick
+    for (const mb of score.masterBars) mbStart.set(mb.index, mb.start || 0);
+    const absStartOf = (bar) => mbStart.get(bar.index) || 0;
+
+    // tempo + time sig from first master bar
+    let tempo = score.tempo || 120;
+    const tempoAuto = score.masterBars[0] && score.masterBars[0].tempoAutomations;
+    if (tempoAuto && tempoAuto.length && tempoAuto[0].value) tempo = tempoAuto[0].value.bpm || tempo;
+    let tsNum = 4, tsDen = 4;
+    const mb0 = score.masterBars[0];
+    if (mb0) { tsNum = mb0.timeSignatureNumerator || 4; tsDen = mb0.timeSignatureDenominator || 4; }
+
+    const tracks = [];
+    const nameCount = {};
+    for (const t of score.tracks) {
+        if (isDrumTrack(t) && !opts.includeDrums) continue;
+        const built = buildTrackEvents(t, absStartOf);
+        if (!built) continue;
+        // disambiguate duplicate names
+        let name = built.name;
+        nameCount[name] = (nameCount[name] || 0) + 1;
+        if (nameCount[name] > 1) name = `${name} (${nameCount[name]})`;
+        tracks.push({ ...built, name });
+    }
+
+    const result = { input: inputPath, tempo: Math.round(tempo), timeSignature: { numerator: tsNum, denominator: tsDen }, tracks };
+    process.stdout.write(JSON.stringify(result));
+}
+
+main();

midi_to_gp5.py

@@ -0,0 +1,413 @@
+#!/usr/bin/env python3
+"""
+Convert a keyswitched MIDI file (output of gp5_to_keyswitched_mid.py) back
+to a Guitar Pro 5/6 file.
+
+This is the inverse of gp5_to_keyswitched_mid.py. The forward script reads
+GP5 articulations from note.effect.* and emits keyswitch notes; this
+script reads keyswitch notes and reconstructs note.effect.* on each
+pitched note.
+
+Supported keyswitches (Metal-GTX mapping):
+    MIDI 9  (A-1)  -> Harmonic (natural)
+    MIDI 17 (F0)   -> Sustain (default, no effect)
+    MIDI 18 (F#0)  -> Sustain (default, no effect)
+    MIDI 20 (G#0)  -> Palm Mute
+    MIDI 23 (B0)   -> Slide Down
+    MIDI 24 (C1)   -> Slide Up
+    MIDI 26 (D1)   -> Hammer
+    MIDI 27 (D#1)  -> Slide In (grace note)
+    MIDI 91 (G6)   -> Bend
+
+Limitations:
+    - Bent note shape is not reconstructed (pitch wheel automation is
+      rarely present in keyswitched MIDI; we use a default 1-semitone bend).
+    - Slide direction is inferred from the next pitched note on the same
+      channel.
+    - Slide-in grace notes are placed at the same tick as the main note,
+      with a 32nd-note duration.
+    - String/fret selection picks the lowest playable fret on the
+      appropriate string (heuristic).
+"""
+import argparse
+import os
+import sys
+from dataclasses import dataclass, field
+
+import guitarpro
+import mido
+
+
+# ---------------------------------------------------------------------------
+# Constants — must match gp5_to_keyswitched_mid.py
+# ---------------------------------------------------------------------------
+DEFAULT_KEYSWITCH_MAP = {
+    17: "sustain",
+    18: "sustain",
+    20: "palm_mute",
+    9:  "harmonic",
+    23: "slide_down",
+    24: "slide_up",
+    26: "hammer",
+    27: "slide_in",
+    91: "bend",
+}
+
+# Standard guitar tuning (low to high): E2 A2 D3 G3 B3 E4
+# In MIDI notes: 40 45 50 55 59 64
+DEFAULT_GUITAR_TUNING = (40, 45, 50, 55, 59, 64)
+
+# Standard bass tuning (low to high): E1 A1 D2 G2
+DEFAULT_BASS_TUNING = (28, 33, 38, 43)
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+@dataclass
+class PitchedNote:
+    """A pitched note (MIDI note > 30) reconstructed from the MIDI."""
+    pitch: int
+    start_tick: int
+    duration_ticks: int
+    velocity: int
+    channel: int
+    articulation: str = "sustain"  # default; overrides by keyswitch
+    slide_target_pitch: int = None  # for slide_up / slide_down
+
+
+# ---------------------------------------------------------------------------
+# MIDI parsing
+# ---------------------------------------------------------------------------
+def _parse_midi(midi_path):
+    """Read a MIDI file and return (track_name, channel, PitchedNote list).
+
+    Keyswitch notes (< 30) are matched to the next pitched note on the
+    same channel at the same tick (or within a few ticks). The keyswitch
+    determines the articulation of that pitched note.
+    """
+    mid = mido.MidiFile(midi_path)
+    if len(mid.tracks) < 2:
+        raise ValueError(
+            f"MIDI file has only {len(mid.tracks)} tracks; "
+            "expected at least 2 (conductor + audio)."
+        )
+
+    audio_track = mid.tracks[1]
+    name = audio_track.name or "Track"
+
+    # Collect all (tick, event) pairs across the audio track.
+    events = []
+    abs_t = 0
+    for msg in audio_track:
+        abs_t += msg.time
+        if hasattr(msg, "note"):
+            events.append((abs_t, msg))
+
+    # Sort by tick. Within a tick, keep original order (stable).
+    events.sort(key=lambda e: e[0])
+
+    # Walk events and pair on/off.
+    # Track open notes per (channel, pitch).
+    open_notes = {}
+    pending_keyswitches = {}  # (channel, pitch) -> first tick it appeared
+
+    pitched = []
+    abs_t = 0
+    for msg in audio_track:
+        abs_t += msg.time
+        if not hasattr(msg, "note"):
+            continue
+        if msg.type == "note_on" and msg.velocity > 0:
+            if msg.note < 30:
+                # Keyswitch note_on.
+                pending_keyswitches[(msg.channel, msg.note)] = abs_t
+            else:
+                # Pitched note_on.
+                pitch = msg.note
+                key = (msg.channel, pitch)
+                # Find the keyswitch that precedes this note on the same channel.
+                # Prefer the most recent keyswitch on this channel.
+                ks_pitch = None
+                for ks_p_note, ks_tick in pending_keyswitches.items():
+                    if ks_p_note[0] == msg.channel and ks_tick <= abs_t:
+                        if ks_pitch is None or ks_tick > pending_keyswitches.get((msg.channel, ks_pitch), 0):
+                            ks_pitch = ks_p_note[1]
+                articulation = DEFAULT_KEYSWITCH_MAP.get(ks_pitch, "sustain")
+                # Consume the keyswitch for this channel.
+                if ks_pitch is not None:
+                    pending_keyswitches.pop((msg.channel, ks_pitch), None)
+                # Record as open note.
+                open_notes[key] = PitchedNote(
+                    pitch=pitch,
+                    start_tick=abs_t,
+                    duration_ticks=0,  # filled on note_off
+                    velocity=msg.velocity,
+                    channel=msg.channel,
+                    articulation=articulation,
+                )
+        elif msg.type == "note_off" or (msg.type == "note_on" and msg.velocity == 0):
+            key = (msg.channel, msg.note)
+            if key in open_notes:
+                note = open_notes.pop(key)
+                note.duration_ticks = abs_t - note.start_tick
+                if note.duration_ticks < 1:
+                    note.duration_ticks = 1
+                pitched.append(note)
+
+    # Resolve slide direction: for each slide_up / slide_down note, find
+    # the next pitched note on the same channel and compare pitches.
+    for i, note in enumerate(pitched):
+        if note.articulation not in ("slide_up", "slide_down"):
+            continue
+        for later in pitched[i + 1:]:
+            if later.channel == note.channel:
+                if later.pitch > note.pitch:
+                    note.slide_target_pitch = later.pitch
+                    # Direction stays as inferred by keyswitch.
+                elif later.pitch < note.pitch:
+                    note.slide_target_pitch = later.pitch
+                break
+
+    return name, mid.tracks[0], pitched
+
+
+# ---------------------------------------------------------------------------
+# GP5 construction
+# ---------------------------------------------------------------------------
+def _pick_string_fret(pitch, tuning):
+    """Pick the lowest playable fret on the appropriate string.
+
+    Handles notes below the lowest open string by using negative frets
+    (Guitar Pro supports frets 0-24, but our tuning may not reach low
+    enough notes for some songs). If the pitch is below the lowest open
+    string, we drop-tune by transposing the string value down.
+    """
+    best = None
+    for string_idx, open_note in enumerate(tuning):
+        fret = pitch - open_note
+        if fret < 0 or fret > 24:
+            continue
+        # Prefer the lowest fret (closest to nut).
+        if best is None or fret < best[1]:
+            best = (string_idx, fret)
+    if best is not None:
+        return best
+    # Pitch is below all strings. Drop-tune: transpose the lowest string
+    # down so the note is reachable. This is a hack for non-standard
+    # tunings; ideally the user would pass the right tuning.
+    lowest_open = tuning[0]
+    fret = pitch - (lowest_open - 12)  # drop the lowest string by 12 semitones
+    if fret < 0 or fret > 24:
+        return None, None
+    return (0, fret)
+
+
+def _articulation_to_effect(note, gp_note):
+    """Set gp_note.effect fields based on the articulation."""
+    art = note.articulation
+    if art == "palm_mute":
+        gp_note.effect.palmMute = True
+    elif art == "harmonic":
+        gp_note.effect.harmonic = guitarpro.NaturalHarmonic()
+    elif art in ("slide_up", "slide_down"):
+        gp_note.effect.slides = [guitarpro.SlideType.shiftSlideTo]
+    elif art == "hammer":
+        gp_note.effect.hammer = True
+    elif art == "slide_in":
+        # Grace note with transition=slide at the target pitch.
+        gp_note.effect.grace = guitarpro.GraceEffect(
+            duration=32,
+            fret=note.pitch % 12,
+            isDead=False,
+            isOnBeat=True,
+            transition=guitarpro.GraceEffectTransition.slide,
+            velocity=note.velocity,
+        )
+    elif art == "bend":
+        # Default to a 1-semitone bend. (Pitch wheel automation is not
+        # reconstructed from MIDI; this is a placeholder.)
+        gp_note.effect.bend = guitarpro.BendEffect(
+            type=guitarpro.BendType.bend,
+            value=0,
+            points=[
+                guitarpro.BendPoint(0, 0, False),
+                guitarpro.BendPoint(3, 4, False),
+                guitarpro.BendPoint(12, 4, False),
+            ],
+        )
+
+
+def _ticks_to_duration(ticks, ticks_per_beat, beats_to_grid):
+    """Convert ticks to a GP5 Duration object.
+
+    GP5 represents durations as discrete values (1=whole, 2=half, 4=quarter,
+    8=eighth, 16=sixteenth, 32=thirty-second). We round to the nearest.
+    """
+    beats = ticks / ticks_per_beat
+    value = round(4 / beats)  # 4/quarter = 4/1, 4/half = 2, etc.
+    value = max(1, min(64, value))
+    if value == 1:
+        return guitarpro.Duration(value=1, isDotted=False, tuplet=guitarpro.Tuplet(1, 1))
+    if value == 3:
+        return guitarpro.Duration(value=2, isDotted=True, tuplet=guitarpro.Tuplet(1, 1))
+    return guitarpro.Duration(value=value, isDotted=False, tuplet=guitarpro.Tuplet(1, 1))
+
+
+def _build_track(name, pitched, tuning, channel, ticks_per_beat):
+    """Build a GP5 Track from a list of PitchedNotes."""
+    song = guitarpro.Song()
+    track = guitarpro.Track(song=song)
+    track.name = name
+    track.channel = guitarpro.MidiChannel(channel=channel, instrument=25)
+    track.strings = [guitarpro.GuitarString(number=i + 1, value=t) for i, t in enumerate(tuning)]
+    track.isPercussionTrack = False
+    track.fretCount = 24
+
+    # Determine measure count from the latest note.
+    if not pitched:
+        return track
+    max_tick = max(n.start_tick + n.duration_ticks for n in pitched)
+    ticks_per_measure = ticks_per_beat * 4  # assume 4/4
+    num_measures = max(1, (max_tick + ticks_per_measure - 1) // ticks_per_measure)
+
+    # Build one Measure per row.
+    measures = []
+    for measure_idx in range(int(num_measures)):
+        measure_start = measure_idx * ticks_per_measure
+        measure_end = measure_start + ticks_per_measure
+        h = guitarpro.MeasureHeader(
+            timeSignature=guitarpro.TimeSignature(
+                numerator=4,
+                denominator=guitarpro.Duration(value=4, isDotted=False, tuplet=guitarpro.Tuplet(1, 1)),
+            ),
+        )
+        m = guitarpro.Measure(track=track, header=h)
+        m.voices[0].beats = []
+        # Group notes that start in this measure's beat slots.
+        # Create one beat per beat (quarter note). Multiple notes can
+        # share a beat (chord).
+        beats_in_measure = 4  # 4/4
+        beat_positions = []
+        for b in range(beats_in_measure):
+            beat_start = measure_start + b * ticks_per_beat
+            beat_end = beat_start + ticks_per_beat
+            # Find notes that start in this beat slot.
+            beat_notes = [n for n in pitched
+                          if beat_start <= n.start_tick < beat_end]
+            beat_positions.append((beat_start, beat_notes))
+
+        for beat_start, beat_notes in beat_positions:
+            if not beat_notes:
+                # Empty beat: skip (no note, no beat).
+                continue
+            # Use the first note's duration as the beat duration.
+            first = beat_notes[0]
+            beat_dur = _ticks_to_duration(first.duration_ticks, ticks_per_beat, 4)
+            beat = guitarpro.Beat(
+                voice=m.voices[0],
+                notes=[],
+                duration=beat_dur,
+                start=beat_start,
+            )
+            for note in beat_notes:
+                string, fret = _pick_string_fret(note.pitch, tuning)
+                if string is None:
+                    continue
+                gp_note = guitarpro.Note(
+                    beat=beat,
+                    string=string + 1,
+                    value=fret,
+                    velocity=note.velocity,
+                    type=guitarpro.NoteType.normal,
+                )
+                _articulation_to_effect(note, gp_note)
+                beat.notes.append(gp_note)
+            if beat.notes:
+                m.voices[0].beats.append(beat)
+
+        measures.append(m)
+
+    track.measures = measures
+    return track
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+def main():
+    parser = argparse.ArgumentParser(
+        description="Convert a keyswitched MIDI back to a Guitar Pro 5/6 file.",
+    )
+    parser.add_argument("midi", help="Path to the input MIDI file.")
+    parser.add_argument("output", help="Path to the output .gp5/.gp file.")
+    parser.add_argument("--instrument", choices=["guitar", "bass", "drums"],
+                        default="guitar")
+    args = parser.parse_args()
+
+    midi_path = os.path.abspath(args.midi)
+    output_path = os.path.abspath(args.output)
+
+    if not os.path.exists(midi_path):
+        print(f"ERROR: MIDI file not found: {midi_path}", file=sys.stderr)
+        return 1
+
+    print(f"Reading {midi_path}...")
+    name, conductor_track, pitched = _parse_midi(midi_path)
+    print(f"  Track name: {name!r}")
+    print(f"  Pitched notes: {len(pitched)}")
+    # Count by articulation.
+    from collections import Counter
+    arts = Counter(n.articulation for n in pitched)
+    for art, count in arts.most_common():
+        print(f"    {art:12s} {count}")
+
+    if not pitched:
+        print("ERROR: no pitched notes found in MIDI", file=sys.stderr)
+        return 1
+
+    # Get ticks_per_beat from MIDI.
+    mid = mido.MidiFile(midi_path)
+    ticks_per_beat = mid.ticks_per_beat
+
+    # Choose tuning.
+    if args.instrument == "guitar":
+        tuning = DEFAULT_GUITAR_TUNING
+    elif args.instrument == "bass":
+        tuning = DEFAULT_BASS_TUNING
+    else:
+        tuning = DEFAULT_GUITAR_TUNING  # ignored for drums
+
+    # Determine channel from the first note.
+    channel = pitched[0].channel
+
+    # Build the song.
+    song = guitarpro.Song()
+    song.tempo = 120  # overwritten below
+    # Extract tempo from conductor.
+    for msg in conductor_track:
+        if msg.type == "set_tempo":
+            song.tempo = int(60_000_000 / msg.tempo)
+            break
+
+    # Song starts with a default Track 1; replace it with our built track.
+    track = _build_track(
+        name=name, pitched=pitched, tuning=tuning,
+        channel=channel, ticks_per_beat=ticks_per_beat,
+    )
+    # The Track already has a MidiChannel from the build helper; ensure
+    # it points at the source file's channel.
+    track.channel = guitarpro.MidiChannel(channel=channel, instrument=25)
+    song.tracks[0] = track
+
+    print(f"Writing {output_path}...")
+    parent = os.path.dirname(output_path)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    guitarpro.write(song, output_path)
+    print(f"OK: wrote {output_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

midjson_to_mid.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+midjson_to_mid.py
+=================
+Consume the JSON event stream emitted by gp_to_keyswitched_mid.js and write
+one Type-1 MIDI file per track into <out_dir>, named <TrackName>_keyswitched.mid.
+
+Usage:
+    node gp_to_keyswitched_mid.js input.gp out_dir > events.json
+    python midjson_to_mid.py events.json <out_dir>
+"""
+import json
+import os
+import re
+import sys
+
+import mido
+
+_FORBIDDEN = re.compile(r'[\\/:\*\?"<>\|]+')
+_WS = re.compile(r'\s+')
+
+
+def sanitize(name, default="output"):
+    cleaned = _FORBIDDEN.sub(' ', name or '')
+    cleaned = _WS.sub(' ', cleaned).strip().rstrip('. ')
+    return cleaned or default
+
+
+def write_track(mid, name, channel, events, ticks_per_beat=960):
+    track = mid.add_track(name[:127] if name else "Guitar")
+    last = 0
+    for e in events:
+        tick = max(0, int(e['tick']))
+        kind = e['kind']
+        note = int(e['note'])
+        vel = int(e.get('velocity', 0))
+        if kind == 'note_on' and vel > 0:
+            msg = mido.Message('note_on', channel=channel, note=note,
+                               velocity=max(1, min(127, vel)), time=tick - last)
+        else:
+            msg = mido.Message('note_off', channel=channel, note=note,
+                               velocity=0, time=tick - last)
+        track.append(msg)
+        last = tick
+    return track
+
+
+def main():
+    if len(sys.argv) < 3:
+        print("Usage: python midjson_to_mid.py <events.json> <out_dir>",
+              file=sys.stderr)
+        return 2
+    events_path = sys.argv[1]
+    out_dir = sys.argv[2]
+    with open(events_path, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+
+    os.makedirs(out_dir, exist_ok=True)
+    tempo = int(data.get('tempo', 120))
+    ts = data.get('timeSignature', {})
+    ts_num = int(ts.get('numerator', 4))
+    ts_den = int(ts.get('denominator', 4))
+
+    written = []
+    for tr in data.get('tracks', []):
+        events = tr['events']
+        if not events:
+            continue
+        mid = mido.MidiFile(type=1, ticks_per_beat=960)
+        conductor = mid.add_track("Conductor")
+        conductor.append(mido.MetaMessage(
+            'set_tempo', tempo=mido.bpm2tempo(tempo), time=0))
+        conductor.append(mido.MetaMessage(
+            'time_signature', numerator=ts_num, denominator=ts_den, time=0))
+        write_track(mid, tr['name'], int(tr['channel']), events)
+        fname = sanitize(tr['name']) + "_keyswitched.mid"
+        out_path = os.path.join(out_dir, fname)
+        mid.save(out_path)
+        # stats
+        ks_notes = sum(1 for e in events if e['kind'] == 'note_on' and e.get('ks'))
+        played = sum(1 for e in events if e['kind'] == 'note_on' and not e.get('ks'))
+        written.append((out_path, tr['name'], tr['channel'], len(events), ks_notes, played))
+
+    for out_path, name, ch, nev, ks, played in written:
+        size = os.path.getsize(out_path)
+        print(f"  {os.path.basename(out_path)}  ({size:,}B, ch={ch}) "
+              f"events={nev} keyswitch_on={ks} played_notes={played}")
+    print(f"\nWrote {len(written)} file(s) to {out_dir}")
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package.json

@@ -0,0 +1,29 @@
+{
+  "name": "stable-jam",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Jam Buddy — an AI music companion that listens to what you play and joins in, at your tempo, in the instrument you pick. Built for the Stability AI Challenge at Music Hackspace Montreal.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20",
+    "pnpm": ">=9"
+  },
+  "packageManager": "pnpm@9.15.9",
+  "workspaces": [
+    "apps/*",
+    "packages/*",
+    "services/*"
+  ],
+  "scripts": {
+    "dev": "pnpm --filter @patterntalk/web dev",
+    "build": "pnpm -r build",
+    "test": "pnpm -r test",
+    "test:web": "pnpm --filter @patterntalk/web test",
+    "lint": "pnpm -r lint",
+    "typecheck": "pnpm -r typecheck",
+    "clean": "pnpm -r exec rm -rf node_modules dist .next"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}