# Plan: Apply & Install `md/34_VST_LINUX.md` (Revised per `md/35_VST_PLAN.md` + `md/35.1_VST_FIX.md`)

## Context Summary

- **Dockerfile** already has `libgl1`, `libasound2`, `libjack-jackd2-0`, `libfreetype6`, Xvfb, fluidsynth. Missing `libcurl4`.
- `requirements.txt` has `mido` but missing `sf2utils`.
- `app/core/vst_engine.py` has `PluginManager` with FluidSynth C-API-based `list_soundfont_instruments()`.
- `app/core/render_engine.py` FluidSynth path hardcodes `program_select(0, fid, 0, 0)`.
- `app/static/js/services/aiGateway.js` — `generate_multitrack_midi` tool has NO `soundfont_id`/`soundfont_bank`/`soundfont_program`.
- `soundfontPlayer.js` — oscillator-based, uses `program` only for ADSR/osc-type selection; no `controllerChange()` or `programChange()` channel-state methods.
- No `soundfont_catalog.json` generation or catalog API endpoint.
- `docker-compose.yml` mounts `.` to `/app`.

---

## 5 Mandatory Refinements (from 35_VST_PLAN.md)

1. **Condensed Catalog for AI**: `get_condensed_catalog_summary()` → max 40–50 instruments categorized by GM groups (Piano, Organ, Guitar, Bass, Strings, Ensemble, Brass, Reed, Pipe, Synth Lead, Synth Pad, Drum Kit). Avoids token overflow.
2. **Non-Blocking Catalog Generation**: `generate_full_catalog()` runs on first API access, not on startup. Cache in memory; refresh on SF2 upload via background task.
3. **Dual Directory Scanning**: system `/opt/daw_engine/soundfonts/` AND user uploads `app/storage/uploads/soundfonts/`.
4. **DecentSampler CWD Fix**: `os.chdir()` to `.dspreset` parent directory before `load_preset()`, so relative `samples/*.wav` paths resolve.
5. **Robust Error Handling**: per-file `try/except` in `SoundFontInspector` — skip corrupted SF2 files with warning instead of crashing.

---

## Task A: SoundFont Inspection Engine (sf2utils)

### A1 — Add dependency
- Add `sf2utils>=0.9.0` to `requirements.txt`.

### A2 — Create `app/core/soundfont_inspector.py`
- `inspect_sf2_file(filepath)` — wrapped in `try/except` per Refinement 5. Returns `{soundfont_id, filename, total_instruments, instruments: [{bank, program, name, is_percussion}]}`.
- `generate_full_catalog(output_json_path)` — scans system dir `/opt/daw_engine/soundfonts/` + user upload dir (Refinement 3). Writes `soundfont_catalog.json`.
- `get_condensed_catalog_summary()` — returns categorized dict with ≤50 entries per Refinement 1. Groups instruments by GM category (Piano=0-7, Chromatic Perc=8-15, Organ=16-23, Guitar=24-31, Bass=32-39, Strings=40-47, Ensemble=48-55, Brass=56-63, Reed=64-71, Pipe=72-79, Synth Lead=80-89, Synth Pad=90-103, Drum Kit=128).
- `invalidate_catalog_cache()` — resets in-memory cache; called after SF2 upload.

### A3 — API Endpoint `GET /api/v1/plugins/soundfonts/catalog`
- In `app/api/v1/plugins.py`:
  - Response shape: `{ full_catalog: {...}, condensed_catalog: {...} }`.
  - Lazily generate on first call, cache in memory (Refinement 2).
  - `POST /upload-soundfont` success handler: calls `invalidate_catalog_cache()` + triggers a background task (FastAPI `BackgroundTasks`) to re-scan. Does NOT block HTTP response.

### A4 — JS API wrapper
- In `app/static/js/services/api.js`, add `SonicAPI.getSoundfontCatalog()` → `GET /api/v1/plugins/soundfonts/catalog`.

---

## Task B: DecentSampler + Pianobook Support

### B1 — Dockerfile updates
- Add `libcurl4` to `apt-get install`.
- Pre-create `/opt/daw_engine/vst3/` and `/opt/daw_engine/samples/pianobook/` with `mkdir -p`.

### B2 — Host dirs
- Create `vst_plugins/` and `samples/pianobook/` at repo root. Add both to `.gitignore`.

### B3 — DecentSamplerManager in `app/core/vst_engine.py`
- `create_decent_sampler_instance(dspreset_path)`:
  - Resolve to absolute path with `os.path.abspath()`.
  - Save original CWD with `os.getcwd()`, then `os.chdir()` to `.dspreset` parent dir before `load_preset()` (Refinement 4).
  - Restore original CWD in `finally` block.
  - Return `VST3Plugin` instance ready for rendering.

### B4 — Wire into `app/core/render_engine.py`
- If track selects a Pianobook instrument (e.g. `instrument_source: "pianobook"`), route through `DecentSamplerManager` instead of FluidSynth or synth fallback.
- The Pianobook path uses `pedalboard.Pedalboard([vst])` with MIDI messages, same as other VST3 paths.

---

## Task C: AI Tool Schema & Prompt Injection

### C1 — Update `generate_multitrack_midi` tool in `aiGateway.js`
- Add to `parameters.properties.tracks.items.properties`:
  - `soundfont_id`: `{ type: "string", description: "ID of the SoundFont file (e.g. 'generaluser_gs')" }`
  - `soundfont_bank`: `{ type: "integer", default: 0, description: "MIDI Bank. 0 = melodic, 128 = drums/percussion" }`
  - `soundfont_program`: `{ type: "integer", description: "MIDI Program number 0-127 from instrument catalog" }`
- Add all 3 to `required` array.

### C2 — Inject condensed catalog into system instruction
- Modify `buildUserMessage()` in `aiGateway.js`:
  - When `systemInstruction` is empty and global `window.__soundfontCatalog` exists, prepend a `system` message block containing the condensed catalog text.
  - Format: one line per GM category with bank/program examples.
  - **Enforce bank rule** (per 35.1_VST_FIX.md §3.B): Add explicit instruction — _`soundfont_bank: 0` for all melodic instruments, `soundfont_bank: 128` for Drum Kits._

### C3 — Fetch catalog on frontend startup
- In `app/static/js/app.jsx`, after auth check, call `SonicAPI.getSoundfontCatalog()`.
- Store result in `window.__soundfontCatalog = { condensed_catalog, full_catalog }`.
- Re-fetch after any SF2 upload succeeds.

---

## Task D: Server Render — Program Change & Channel Mapping

### D1 — Read bank/program from track metadata
- In `render_engine.py` MIDI rendering block, extract `soundfont_bank` and `soundfont_program` from track dict.
- Default: bank=0, program=0.

### D2 — MIDI channel routing + FluidSynth update
- **Channel rules** (per 35.1_VST_FIX.md §5.B):
  - `bank == 128` or track has `is_percussion: true` → `midi_channel = 9` (GM channel 10, percussion).
  - Otherwise → assign channels sequentially from 0–8, one per unique percussion-group track.
- Replace hardcoded `fl.program_select(0, fid, 0, 0)` with:
  ```python
  midi_channel = 9 if (bank == 128 or track.get("is_percussion")) else channel_counter
  fl.program_select(midi_channel, fid, bank, prog)
  ```
- All note_on/note_off events for that track must use the same `midi_channel`.

### D3 — VST3/Pedalboard path: CC + PC insertion
- Extend `midi_events_to_messages()` or add a wrapper that inserts two MIDI messages at sample_offset=0 before note messages:
  - `MidiMessage(control_change=0, value=bank, sample_offset=0)` — CONTROL_CHANGE CC 0 (Bank Select MSB)
  - `MidiMessage(program_change=program, sample_offset=0)` — PROGRAM_CHANGE
- These are prepended to the message list before `Pedalboard([vst])` processes the buffer.

---

## Task E: Client SoundFont Player — Program Change & Channel Allocation

### E1 — Add channel-state tracking to `soundfontPlayer.js`
- Add internal `_channels` array (size 16), each entry: `{ bank: 0, program: 0 }`.
- `controllerChange(channel, controller, value)`:
  - If `controller === 0` (Bank Select MSB), store `bank` for that channel.
- `programChange(channel, program)`:
  - Store `program` for that channel.
- Modify `playNote()` to accept an optional `channel` parameter and use the stored bank/program for ADSR/osc-type selection.

### E2 — Add `applyAITrackInstrument(trackId, bank, program)`
- New function in `soundfontPlayer.js`:
  - Determine MIDI channel: `bank === 128 || isPercussion ? 9 : track_index % 9`.
  - Call `controllerChange(channel, 0, bank)`.
  - Call `programChange(channel, program)`.
- Called from `app.jsx` after AI returns `generate_multitrack_midi` with track instrument data.

### E3 — Wire into post-AI pipeline in `app.jsx`
- In the DAW command dispatch loop (around line 12853), after processing `generate_multitrack_midi` function call:
  - For each returned track with `soundfont_bank`/`soundfont_program`, call `applyAITrackInstrument()`.
  - Log the action to `aiActionLog`.

---

## Task F: Background Cache Invalidation on Upload

### F1 — Update `POST /upload-soundfont` in `plugins.py`
- After saving the uploaded SF2 file:
  1. Call `SoundFontInspector.invalidate_catalog_cache()`.
  2. Use FastAPI `BackgroundTasks` to queue a re-scan: `background_tasks.add_task(generate_full_catalog)`.
  3. Return HTTP 200 immediately (not block on scan).

### F2 — Frontend catalog re-fetch after upload
- In `app.jsx` upload handler, after `SonicAPI.uploadSoundFont()` succeeds, call `SonicAPI.getSoundfontCatalog()` and update `window.__soundfontCatalog`.

---

## Task G: Validation

### G1 — Catalog API
- `GET /api/v1/plugins/soundfonts/catalog` → valid JSON with `{ full_catalog: {...}, condensed_catalog: {...} }`.
- Condensed catalog contains ≤50 entries, grouped by GM category.

### G2 — AI generation
- Input: _"Compose 8 bars of Brass horns and a drum kit"_
- Verify AI returns `generate_multitrack_midi` call with:
  - Brass track: `program: 56`, `bank: 0`, `soundfont_id: "generaluser_gs"`.
  - Drums track: `program: 0`, `bank: 128`, `soundfont_id: "generaluser_gs"`.

### G3 — Client instrument switching
- After AI response, verify `applyAITrackInstrument` is called with correct bank/program per track.
- Verify MIDI channel allocation: melodic → ch0-8, drums → ch9.
- Verify `controllerChange(CC0)` + `programChange()` dispatched per channel.

### G4 — Server render
- Export WAV, verify correct Brass horn and Drum sound.
- For FluidSynth path: confirm `program_select` uses correct channel, bank, program.
- For VST3 path: confirm CC0 + PC inserted before notes.

### G5 — Upload cache invalidation
- Upload a new `.sf2` file → verify `catalog` endpoint updates without manual restart.
- Upload a corrupted `.sf2` file → verify it is skipped gracefully (Refinement 5).

### G6 — Regression
- `pytest tests/` passes with no regressions.

---

## Implementation Order

1. **A1–A4** (sf2utils + soundfont_inspector + catalog API + JS wrapper) — foundational.
2. **C1–C3** (AI tool schema + condensed prompt injection + startup fetch) — depends on A3/A4.
3. **D1–D3** (server render program change + channel mapping + CC/PC insertion) — depends on C1 for field names.
4. **F1–F2** (background cache invalidation on upload) — depends on A3.
5. **E1–E3** (client program change + channel allocation + post-AI wiring) — independent of D, but shares channel routing logic.
6. **B1–B4** (DecentSampler) — last, requires manual VST3 binary download.
7. **G1–G6** (validation).