# 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.