File size: 2,495 Bytes
b2e4883 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | # 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.
|