fix: play các soundfont và có thể tắt các âm khi thả phím

Khi load SF2, preset lookup của program_change dùng search order
(lần lượt qua các SF đã load). Track 1 load SF2→SF2 presets override
SF1 trên tất cả channel, track 2 chọn nhầm preset của SF2.
Fix: program_select(synth, ch, sfHandle, bank, prog) chỉ định rõ
SoundFont ID, không phụ thuộc search order.

.gitignore

@@ -18,6 +18,10 @@ app/storage/processed/*
 !app/storage/uploads/.gitkeep
 !app/storage/processed/.gitkeep
 .DS_Store
+
+# VST3 and sample library directories (proprietary binaries)
+vst_plugins/
+samples/
 .idea/
 .vscode/
 *.log

.kilo/plans/1785058528193-vst3-soundfont-engine-plan.md

@@ -0,0 +1,206 @@
+# Technical Analysis & Implementation Plan: SF3 + SpessaSynth Client (md/37_SF_CONVERT.md)
+
+## 1. Assessment Summary
+
+The spec proposes 2 steps:
+1. **Server**: Convert `.sf2` → `.sf3` (Ogg Vorbis compressed) via `mscore` CLI
+2. **Client**: Replace oscillator emulation with SpessaSynth library for authentic SoundFont playback
+
+### Current State vs Spec
+
+| Requirement | Status | Impact |
+|---|---|---|
+| `mscore` in Dockerfile | ❌ Not installed | 200MB+ dependency |
+| `soundfont_converter.py` | ❌ Does not exist | Needs creation |
+| `GET /soundfonts/download/{sf_id}` endpoint | ❌ Missing | Blocks client download |
+| `spessasynth_lib` CDN import in `index.html` | ❌ Not present | Blocks client upgrade |
+| `soundfontStorage.js` (IndexedDB) | ❌ Not created | Needed for caching |
+| `SonicSF.init(audioCtx)` | ❌ Not called anywhere | New integration point |
+| `playNote` signature compat | ⚠️ Spec uses 4 params, codebase uses 6–8 | Must bridge |
+| `applyAITrackInstrument` signature | ⚠️ Spec has `channel` first, code passes it last | Must bridge |
+
+### Key Risk: `mscore` Dependency
+
+`mscore` (MuseScore) pulls in Qt, fontconfig, audio drivers — easily 200-400MB in the container. **Alternative approaches:**
+
+1. **`fluidsynth` built-in conversion**: `fluidsynth` already installed (`libfluidsynth3`, `pyfluidsynth`). Can convert SF2→SF3 via `--convert` flag or using `fluid_synth_sffd_*` APIs, but the low-level Python bindings don't expose this.
+
+2. **`sf2convert`/`sf2pack`**: Smaller tools, but less commonly packaged.
+
+3. **Python + `libsndfile`/`pydub`/`ogg`**: Parse SF2, extract WAV samples, compress to Ogg, rebuild SF3 structure. Complex — would need a SF2 parser and Ogg encoder.
+
+4. **Python `acousticbrainz-sf2convert`**: Lightweight Python library specifically for SF2↔SF3.
+
+**Recommendation**: Install `mscore` via `apt-get install -y mscore --no-install-recommends` to minimize deps. If the image grows too much (~1.5GB+), fall back to `fluidsynth` command-line conversion (`fluidsynth --convert`).
+
+### Key Risk: `playNote` API Compatibility
+
+The spec's proposed API:
+```javascript
+playNote(pitch, velocity=0.8, durationSec=1.0, channel=0)
+```
+
+Current callers use:
+```javascript
+playNote(pitch, velocity, durationMs, startTime, program, destinationNode, channel?, synthEngine?)
+```
+
+**Strategy**: Don't replace. Instead, wrap SpessaSynth inside the existing `SonicSF` object. Map:
+- `velocity` (0–1) → MIDI velocity (1–127)
+- `startTime` → if in future, use `setTimeout` for note scheduling (not perfect but adequate for preview)
+- `destinationNode` → SpessaSynth routes to its own internal destination, but can add a gain node stage
+- `program` → internal `_channels[channel].program` state (as now), but SpessaSynth also gets `programChange(ch, program)`
+- `synthEngine` → load the right SF3 and set bank/program on SpessaSynth
+
+**Backward compat**: Keep ALL existing methods. Add SpessaSynth as an optional enhanced engine. If SpessaSynth isn't loaded (CDN fails), fall back to oscillator emulation.
+
+---
+
+## 2. Implementation Plan
+
+### Task 1 — Server: SF2→SF3 Conversion Pipeline
+
+#### 1.1 Docker Dependency
+- `Dockerfile`: Add `mscore` with `--no-install-recommends`
+  ```dockerfile
+  RUN apt-get install -y --no-install-recommends mscore && rm -rf /var/lib/apt/lists/*
+  ```
+- Test: `docker compose build` — measure image size delta
+
+#### 1.2 `app/core/soundfont_converter.py`
+- `SoundFontConverter` class with:
+  - `convert_sf2_to_sf3(sf2_path)` → runs `mscore -o output.sf3 input.sf2`
+  - `batch_convert_all()` → walks `target_dirs`, converts missing `.sf3`
+  - `target_dirs` = `["/opt/daw_engine/soundfonts", "app/storage/uploads/soundfonts"]`
+  - Progress logging, error handling, cache validation (skip if `.sf3` newer than `.sf2`)
+- Integrate with server startup:
+  - In `app/main.py` startup event, call `SoundFontConverter().batch_convert_all()` as background task (non-blocking, don't delay boot)
+
+#### 1.3 API Download Endpoint
+- `app/api/v1/plugins.py`: Add:
+  ```python
+  @router.get("/soundfonts/download/{sf_id}")
+  async def download_soundfont_asset(sf_id: str):
+      # Search system_dir, upload_dir for .sf3 or .sf2
+      # Return FileResponse
+      # Fallback: .sf3 → .sf2 → 404
+  ```
+- Use `_find_sf2_path` from `render_engine.py` logic (case-insensitive, multi-dir)
+- Set `media_type="application/octet-stream"` and proper `Content-Disposition`
+
+#### 1.4 Update `SoundFontInspector` to Also Scan `.sf3`
+- `soundfont_inspector.py:80`: Change `.sf2` filter to `('.sf2', '.sf3')`
+- Ensure the catalog includes `.sf3` files as available instruments
+
+---
+
+### Task 2 — Client: SpessaSynth Integration
+
+#### 2.1 `index.html` — Add SpessaSynth CDN
+```html
+<script type="module">
+  import { Synthesizer } from 'https://cdn.jsdelivr.net/npm/spessasynth_lib@latest/dist/spessasynth_lib.js';
+  window.SpessaSynthClass = Synthesizer;
+</script>
+```
+- Add BEFORE `soundfontPlayer.js` so the class is available when the player initializes
+
+#### 2.2 `app/static/js/services/soundfontStorage.js` — IndexedDB Cache
+- `SoundFontStorage` class with `openDB()`, `getBuffer(sfId)`, `saveBuffer(sfId, arrayBuffer)`
+- Uses `indexedDB` with DB name `"DAW_SoundFont_Cache"`, store name `"sf3_buffers"`
+- Export singleton `sfStorage`
+
+#### 2.3 `app/static/js/services/soundfontPlayer.js` — Dual-Mode Rewrite
+
+**Architecture**: Keep the existing `window.SonicSF` as the public API. Internally use SpessaSynth when available, fall back to oscillator when not.
+
+**Changes to existing methods:**
+
+| Method | Change |
+|---|---|
+| `init(audioCtx)` | NEW — creates SpessaSynth instance, triggers default SF load |
+| `loadSoundFont(sfId)` | REWORK — try IndexedDB → fetch `/api/v1/plugins/soundfonts/download/{sfId}` → load into SpessaSynth |
+| `playNote(...)` | ADD SpessaSynth path: if initialized, delegate to `synthInstance.noteOn/noteOff`; else use oscillator fallback |
+| `applyAITrackInstrument(bank, program, synthEngine?)` | ADD SpessaSynth path: call `controllerChange` + `programChange` on SpessaSynth |
+| `stopAll()` | ADD SpessaSynth: `allNotesOff(channel)` or `programReset()` |
+| `controllerChange(ch, cc, val)` | ADD SpessaSynth: delegate if initialized |
+| `programChange(ch, prog)` | ADD SpessaSynth: delegate if initialized |
+
+**Backward compat guarantee:**
+- All existing callers continue to work unchanged
+- 6-arg `playNote(pitch, vel, durMs, startTime, program, destNode)` → SpessaSynth ignores `startTime` (schedules immediately) and `destNode` (uses internal routing)
+- 8-arg `playNote(..., channel, synthEngine)` → SpessaSynth uses `synthEngine.soundfont_id` for SF loading, `synthEngine.soundfont_program` for program selection
+- If SpessaSynth not loaded/CDN fails → transparent fallback to existing oscillator code
+
+#### 2.4 `app.jsx` — Integration Points
+
+- **Startup** (in a useEffect or the existing audio context initialization):
+  ```javascript
+  if (window.SonicSF && window.SonicSF.init) {
+    SonicSF.init(getAudioContext());
+  }
+  ```
+- **Synth selection**: After `setTrackInstrumentWithProgram` / `setTrackInstrument`, trigger SF load:
+  ```javascript
+  if (synthEngine && synthEngine.type === 'soundfont') {
+    SonicSF.loadSoundFont(synthEngine.soundfont_id);
+  }
+  ```
+- **AI track creation**: Already calls `applyAITrackInstrument` — SpessaSynth path handles it
+
+---
+
+### Task 3 — Backward Compatibility & Migration
+
+#### 3.1 Fallback Behavior
+- If `window.SpessaSynthClass` is undefined (CDN blocked, offline): fall back to existing oscillator code
+- If `.sf3` download fails: fall back to oscillator
+- If SpessaSynth throws: catch error, log warning, fall back to oscillator
+
+#### 3.2 Testing Matrix
+
+| Scenario | Expected |
+|---|---|
+| SpessaSynth loaded + SF3 cached | Authentic playback, 0ms load |
+| SpessaSynth loaded + SF3 needs download | Authentic playback after 1-2s load |
+| CDN blocked (offline) | Transparent oscillator fallback |
+| SF3 not available on server | Transparent oscillator fallback |
+| MIDI keyboard + armed track | Authentic or oscillator based on availability |
+
+---
+
+## 3. Files Affected
+
+| File | Change |
+|---|---|
+| `Dockerfile` | Add `mscore --no-install-recommends` |
+| `app/core/soundfont_converter.py` | **NEW** — SF2→SF3 convert + batch scan |
+| `app/api/v1/plugins.py` | Add `GET /soundfonts/download/{sf_id}` |
+| `app/core/soundfont_inspector.py` | Accept `.sf3` in scan filter |
+| `app/main.py` | Add startup background conversion |
+| `app/templates/index.html` | Add SpessaSynth CDN `<script type="module">` |
+| `app/static/js/services/soundfontStorage.js` | **NEW** — IndexedDB cache |
+| `app/static/js/services/soundfontPlayer.js` | Dual-mode rewrite (SpessaSynth + oscillator fallback) |
+| `app/static/js/app.jsx` | Add init + SF load calls |
+
+## 4. Validation
+
+```bash
+# Server-side
+docker compose build  # verify mscore installs
+docker compose exec web python -c "from app.core.soundfont_converter import SoundFontConverter; print('OK')"
+curl -s http://localhost:8000/api/v1/plugins/soundfonts/download/sgm_v2.01 | head -c 4 | file -
+docker compose exec web ls -la /opt/daw_engine/soundfonts/*.sf3  # verify conversion
+
+# Client-side
+# Open browser → DevTools → check SpessaSynth loaded (window.SpessaSynthClass)
+# Select SoundFont → check network tab for .sf3 download
+# Play MIDI notes → hear authentic instrument (not oscillator)
+```
+
+## 5. Open Questions
+
+1. **`mscore` image size**: Measure actual delta. If >300MB, consider `fluidsynth --convert` alternative.
+2. **CDN reliability**: SpessaSynth loaded from jsdelivr CDN — consider bundling or NPM install as fallback.
+3. **Startup delay**: `batch_convert_all()` could take minutes for large SF2s. Run as background Celery task, not inline startup.
+4. **SGM_v2.01.sf2 (529MB)**: Conversion time for this file. Need to handle gracefully (streaming, timeout).

.kilo/plans/1785130485229-fluidsynth-wasm-migration-plan.md

@@ -0,0 +1,398 @@
+# Technical Analysis & Implementation Plan: SpessaSynth → FluidSynth WASM Migration
+
+## 1. Key Findings from Codebase Investigation
+
+### 1.1 Current State (SpessaSynth)
+| Aspect | Detail |
+|---|---|
+| Engine | `spessasynth_lib@4.3.1` (CDN via jsDelivr + importmap) |
+| File | `app/static/js/services/soundfontPlayer.js` — IIFE, `window.SonicSF` singleton |
+| API surface | 10 methods: `init`, `playNote`, `stopNote`, `stopAll`, `selectInstrument`, `controllerChange`, `programChange`, `pitchBend`, `sustainActive`, `applyAITrackInstrument`, `allocateChannel`, `getChannelState`, `loadSoundFont` (internal) |
+| Call sites | 45 in `app.jsx` across piano roll, MIDI keyboard, timeline playback, external MIDI input, AI track generation |
+| storage | `app/static/js/services/soundfontStorage.js` — IndexedDB cache, `window.SonicSFStorage` |
+| Server render | `app/core/render_engine.py` uses `pyfluidsynth` (C++ FluidSynth) |
+| Server SF3 | `app/core/soundfont_converter.py` converts SF2→SF3 via `fluidsynth`/`mscore` CLI |
+| API endpoint | `GET /api/v1/plugins/soundfonts/download/{sf_id}` — serves both `.sf2` and `.sf3` |
+| Docker | `libfluidsynth3`, `fluidsynth` CLI installed in container |
+
+### 1.2 Target State (FluidSynth WASM) — Corrected Spec
+
+**CDN package**: `fluidsynth-wasm` does NOT exist on npm/CDN.  
+**Real package**: `@enikey87/fluidsynth-emscripten@0.1.1`  
+
+| File | Size | Purpose |
+|---|---|---|
+| `libfluidsynth-2.3.0-sf3.js` | 130 KB | JS loader, SF3 support, separate WASM |
+| `libfluidsynth-2.3.0-sf3.wasm` | 1.7 MB | WASM binary with Ogg/SF3 support |
+| `libfluidsynth-2.3.0-sf3-all-in-one.js` | 2.39 MB | JS+WASM embedded (no separate .wasm fetch) |
+
+**CDN URL** (chosen: separate .wasm for caching):  
+```
+https://cdn.jsdelivr.net/npm/@enikey87/fluidsynth-emscripten@0.1.1/dist/libfluidsynth-2.3.0-sf3.js
+https://cdn.jsdelivr.net/npm/@enikey87/fluidsynth-emscripten@0.1.1/dist/libfluidsynth-2.3.0-sf3.wasm
+```
+
+### 1.3 CRITICAL Architecture Flaw in Spec
+
+The spec's code (md/39_SF3_NEW.md) passes `wasmModule` and `synthPtr` via `postMessage` to AudioWorklet. **This cannot work** because:
+1. AudioWorklet runs in a separate audio thread with an isolated global scope
+2. `synthPtr` (a C pointer / integer) refers to WASM linear memory in the main thread's `WebAssembly.Module` instance
+3. Loading `libfluidsynth-2.3.0-sf3.js` inside the worklet creates a **separate WASM instance** with its own memory
+4. The spec also uses `_fluid_synth_write_float` inside `process()` — this blocks the audio thread if audio buffer underruns occur
+
+**Correct architecture (per README):**  
+> "To use libfluidsynth-X.X.X.js in AudioWorklet, load it into AudioWorklet before your worklet JS file."
+
+The FluidSynth instance must be created **inside** the AudioWorklet. MIDI events + ArrayBuffer data are sent from main thread to worklet via `port.postMessage`.
+
+### 1.4 `playNote` Signature Complexity
+
+Current `playNote(note, velocity, durationMs, startTime, program, destNode, channel, synthEngine)` has 8 parameters and 16 call sites. The `synthEngine` object carries `{ soundfont_id, soundfont_bank, soundfont_program }` which must be converted to FluidSynth's `bank_select` + `program_change` before `noteon`.
+
+### 1.5 Additional `window.SonicSF` Methods Not in Spec
+
+Must preserve in new implementation:
+- `stopNote(channel, pitch)` — MIDI note-off with extra CC 64/120 cleanup
+- `controllerChange(channel, controller, value)` — MIDI CC forwarding
+- `programChange(channel, program)` — pure JS state tracking
+- `pitchBend(channel, value)` — 14-bit bend value
+- `sustainActive(channel)` — getter for sustain pedal state
+- `allocateChannel(bank)` — channel allocation (percussion = ch 9)
+- `getChannelState(channel)` — JS-side { bank, program, isPercussion } state
+- `saveToIndexedDB / loadFromIndexedDB` — legacy storage
+
+---
+
+## 2. Implementation Plan
+
+### Phase 1: Preparation (Infrastructure)
+
+**Task 1.1 — Create worklet directory**
+```
+mkdir -p app/static/js/worklets/
+touch app/static/js/worklets/.gitkeep
+```
+
+**Task 1.2 — Update `index.html`**
+- Remove SpessaSynth importmap + module script (lines 13-25)
+- Add FluidSynth WASM CDN script:
+```html
+<script src="https://cdn.jsdelivr.net/npm/@enikey87/fluidsynth-emscripten@0.1.1/dist/libfluidsynth-2.3.0-sf3.js"></script>
+```
+
+### Phase 2: AudioWorklet Processor
+
+**Task 2.1 — Create `app/static/js/worklets/fluidsynth-worklet.js`**
+
+This file runs inside AudioWorkletGlobalScope. It:
+- Receives the FluidSynth WASM module (loaded via `addModule()`)
+- Maintains its own `_fluid_synth` instance
+- Receives commands from main thread via `port.onmessage`:
+  - `INIT_SYNTH` — create settings + synth, store `synthPtr`
+  - `LOAD_SF` — receive ArrayBuffer, write to MEMFS, call `_fluid_synth_sfload`
+  - `NOTE_ON` — `_fluid_synth_noteon(synthPtr, channel, pitch, velocity)`
+  - `NOTE_OFF` — `_fluid_synth_noteoff(synthPtr, channel, pitch)`
+  - `CC` — `_fluid_synth_cc(synthPtr, channel, controller, value)`
+  - `PROGRAM_CHANGE` — `_fluid_synth_program_change / bank_select`
+  - `PITCH_BEND` — `_fluid_synth_pitch_bend(synthPtr, channel, value)`
+  - `ALL_NOTES_OFF` / `ALL_SOUNDS_OFF`
+  - `SET_GAIN` — `_fluid_synth_set_gain`
+- In `process(inputs, outputs)`:
+  - Get `synthPtr` from closure
+  - Call `_fluid_synth_write_float(synthPtr, bufferSize, leftPtr, 0, 1, rightPtr, 0, 1)`
+  - Return `true` to keep processor alive
+
+Key constraint: The FluidSynth WASM's `_fluid_synth_write_float` needs access to the output channel Float32Array's **byteOffset** relative to the WASM heap. AudioWorklet `output` arrays are not backed by WASM memory. Two solutions:
+- **A**: After rendering, copy from WASM heap Float32Array to output channels (less efficient but safe)
+- **B**: Load FluidSynth WASM inside worklet, allocate output buffers inside WASM heap (complex)
+
+**Recommendation: Solution A** — simpler and avoids memory management issues.
+
+### Phase 3: Rewrite `soundfontPlayer.js`
+
+**Task 3.1 — Rewrite as IIFE-compatible `window.SonicSF`**
+
+Keep the IIFE pattern (`window.SonicSF = SonicSF`) to minimize diff in `app.jsx`. Internal implementation uses `FluidSynthWasmWorkletBridge` class.
+
+```javascript
+// Internal state
+const _channels = Array.from({ length: 16 }, () => ({ bank: 0, program: 0, isPercussion: false }));
+const _sustainStates = new Array(16).fill(false);
+let _workletNode = null;
+let _audioCtx = null;
+let _initialized = false;
+let _initPromise = null;
+let _currentSfId = null;
+let _sfHandleMap = new Map(); // sfId -> sfHandle (integer, tracked on JS side)
+let _fluidModule = null; // guarded global, used before worklet takes over
+```
+
+**Key architectural decision:**
+
+The FluidSynth instance lives in the AudioWorklet. The main thread `soundfontPlayer.js`:
+1. Loads the WASM module only for FS operations (MEMFS file writing) - needed because worklet can't do `fetch()`
+2. Creates an `AudioWorkletNode`, registers the worklet
+3. Sends ArrayBuffer data + MIDI commands to worklet via `port.postMessage`
+4. Tracks JS-side state (channel, bank, program) for methods like `getChannelState`, `allocateChannel`
+
+**Alternative (simpler, recommended for v1):**  
+Run FluidSynth entirely on **main thread**, render PCM buffers in a rAF/setInterval loop, feed to a `ScriptProcessorNode` or a simple AudioWorklet that just outputs pre-rendered buffers. This avoids the AudioWorklet WASM complexity.
+
+**Decision:** Use main-thread FluidSynth + simple AudioWorklet output. Rationale:
+- Much simpler implementation
+- FluidSynth `_fluid_synth_write_float` is fast enough for real-time rendering
+- No need to manage two WASM instances
+- Can reuse the spec's API surface directly
+- MIDI events can be processed synchronously on main thread
+
+**Architecture:**
+```
+Main thread:
+  FluidSynth Module (loaded via CDN <script> tag)
+    └─ _new_fluid_settings, _new_fluid_synth
+    └─ MEMFS: FS.writeFile('/soundfonts/...', data)
+    └─ _fluid_synth_sfload, _fluid_synth_noteon, etc.
+    └─ _fluid_synth_write_float(bufSize, ...) -> Float32Array
+
+AudioWorklet (simple passthrough):
+  └─ Receives Float32Array PCM buffers via postMessage
+  └─ Outputs to audio destination in process()
+```
+
+### 3.2 Method Implementation Details
+
+**`init(audioCtx)`:**
+```javascript
+async init(audioContext) {
+  this.audioCtx = audioContext;
+  // resolve createFluidSynthModule() from CDN
+  this.fluidModule = await new Promise(resolve => {
+    // libfluidsynth-2.3.0-sf3.js exposes createFluidSynthModule()
+    resolve(window.createFluidSynthModule());
+  });
+  // create settings, synth
+  const settingsPtr = this.fluidModule._new_fluid_settings();
+  this.fluidModule._fluid_settings_setnum(settingsPtr, "synth.sample-rate", this.audioCtx.sampleRate);
+  this.fluidModule._fluid_settings_setnum(settingsPtr, "synth.gain", 1.0);
+  this.synthPtr = this.fluidModule._new_fluid_synth(settingsPtr);
+  // create MEMFS dir
+  this.fluidModule.FS.mkdir('/soundfonts');
+  // create AudioWorklet node
+  this.workletNode = new AudioWorkletNode(this.audioCtx, 'fluidsynth-bridge');
+  this.workletNode.connect(this.audioCtx.destination);
+  // start render loop
+  this._startRenderLoop();
+}
+```
+
+**`_startRenderLoop()`:**
+Uses `requestAnimationFrame` or scheduler to periodically:
+1. Check if worklet Node needs more data
+2. Call `_fluid_synth_write_float` into a Float32Array
+3. Send via `postMessage` to worklet
+
+**`loadSoundFont(sfId)`:**
+```javascript
+async loadSoundFont(sfId) {
+  let buffer = await sfStorage.getBuffer(sfId);
+  if (!buffer) {
+    const resp = await fetch(`/api/v1/plugins/soundfonts/download/${sfId}`);
+    buffer = await resp.arrayBuffer();
+    await sfStorage.saveBuffer(sfId, buffer);
+  }
+  this.fluidModule.FS.writeFile(`/soundfonts/${sfId}.sf3`, new Uint8Array(buffer));
+  const sfHandle = this.fluidModule._fluid_synth_sfload(this.synthPtr, `/soundfonts/${sfId}.sf3`, 1);
+  // store handle
+  return sfHandle !== -1;
+}
+```
+
+**`playNote(note, velocity, durationMs, startTime, program, destNode, channel, synthEngine)`:**
+```javascript
+function playNote(note, velocity, durationMs, startTime, program, destNode, channel, synthEngine) {
+  // Handle synthEngine (bank/program setup)
+  let ch = channel ?? 0;
+  let bank = 0, prog = 0;
+  if (synthEngine) {
+    bank = synthEngine.soundfont_bank ?? 0;
+    prog = synthEngine.soundfont_program ?? 0;
+    this.fluidModule._fluid_synth_bank_select(this.synthPtr, ch, bank);
+    this.fluidModule._fluid_synth_program_change(this.synthPtr, ch, prog);
+  } else if (program !== undefined) {
+    prog = program;
+    this.fluidModule._fluid_synth_program_change(this.synthPtr, ch, prog);
+  }
+  // Note on
+  this.fluidModule._fluid_synth_noteon(this.synthPtr, ch, midiPitch, midiVel);
+  // Schedule note off
+  if (durationMs > 0 && durationMs < 60000) { // skip held notes
+    setTimeout(() => {
+      this.fluidModule._fluid_synth_noteoff(this.synthPtr, ch, midiPitch);
+    }, durationMs);
+  }
+}
+```
+
+**`stopNote(channel, pitch)`:**  
+→ `this.fluidModule._fluid_synth_noteoff(synthPtr, channel, pitch)`  
+Also set sustain off + all notes off (preserve current behavior).
+
+**`stopAll()`:**  
+→ `_fluid_synth_all_notes_off` + `_fluid_synth_all_sounds_off` for all 16 channels.
+
+**`controllerChange(channel, controller, value)`:**  
+→ `this.fluidModule._fluid_synth_cc(synthPtr, channel, controller, value)`  
++ track JS-side state for `_channels[channel].bank`, `_sustainStates[channel]`.
+
+**`pitchBend(channel, value)`:**  
+→ `this.fluidModule._fluid_synth_pitch_bend(synthPtr, channel, value)`.
+
+**`selectInstrument(channel, bank, program, sfId)`:**  
+→ Load SF if needed, then `_fluid_synth_bank_select` + `_fluid_synth_program_change`.
+
+**`sustainActive(channel)`:**  
+→ Return `_sustainStates[channel]` (tracked by `controllerChange` for CC 64).
+
+**`applyAITrackInstrument(bank, program, synthEngine)`:**  
+→ Same as current: allocate channel, call `selectInstrument` with `synthEngine.soundfont_id`.
+
+### Phase 4: Bridge AudioWorklet
+
+**Task 4.1 — Create `app/static/js/worklets/fluidsynth-bridge.js`**
+
+Simple AudioWorkletProcessor that receives pre-rendered PCM buffers:
+```javascript
+class FluidSynthBridge extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.audioQueue = [[], []]; // L/R channel queues
+    this.port.onmessage = (e) => {
+      if (e.data.type === 'PCM_FRAME') {
+        this.audioQueue[0].push(...e.data.left);
+        this.audioQueue[1].push(...e.data.right);
+      }
+    };
+  }
+  process(inputs, outputs) {
+    const out = outputs[0];
+    if (!out) return true;
+    const len = out[0].length;
+    const left = this.audioQueue[0].splice(0, len);
+    const right = this.audioQueue[1].splice(0, len);
+    // Fill output; zero-fill if buffer underrun
+    for (let i = 0; i < len; i++) {
+      out[0][i] = i < left.length ? left[i] : 0;
+      out[1][i] = i < right.length ? right[i] : 0;
+    }
+    return true;
+  }
+}
+registerProcessor('fluidsynth-bridge', FluidSynthBridge);
+```
+
+### Phase 5: Optimize Render Loop
+
+**Task 5.1 — Implement ring-buffer approach**
+
+The render loop must balance latency vs. buffer underruns:
+- Render ~512 samples per frame (≈11.6ms at 44.1kHz)
+- Queue 3 frames ahead (≈35ms buffer → safe against GC pauses)
+- Use `AudioWorkletNode.port.postMessage` with `transferable: true` for zero-copy
+
+Alternative: Use SharedArrayBuffer for lock-free ring buffer (requires COOP/COEP headers).
+
+### Phase 6: Remove SpessaSynth from index.html
+
+**Task 6.1 — Clean up CDN imports**
+- Remove: `<script type="importmap">` block (lines 13-19)
+- Remove: SpessaSynth module script (lines 20-25)
+- Remove: `spessasynth_core` importmap entry
+
+### Phase 7: API Endpoint for WASM asset (optional)
+
+If self-hosting is preferred over CDN, serve `libfluidsynth-2.3.0-sf3.js` and `.wasm` from static files directory.
+
+---
+
+## 3. Files to Modify/Create
+
+| Action | File | Description |
+|---|---|---|
+| **CREATE** | `app/static/js/worklets/fluidsynth-bridge.js` | Bridge AudioWorkletProcessor (PCM passthrough) |
+| **MODIFY** | `app/static/js/services/soundfontPlayer.js` | Rewrite engine from SpessaSynth to FluidSynth WASM; preserve `window.SonicSF` API surface |
+| **MODIFY** | `app/templates/index.html` | Replace SpessaSynth CDN imports with `@enikey87/fluidsynth-emscripten` CDN |
+| **MODIFY** | `app/static/js/services/soundfontStorage.js` | Minor: expose `sfStorage` as named export + `window.SonicSFStorage` (likely no change needed) |
+| **NO CHANGE** | `app/static/js/app.jsx` | Zero changes — `window.SonicSF` API surface preserved |
+| **NO CHANGE** | `app/api/v1/plugins.py` | Download endpoint already serves `.sf2`/`.sf3` correctly |
+| **NO CHANGE** | `app/core/render_engine.py` | Already uses pyfluidsynth (server-side) |
+| **NO CHANGE** | `app/core/soundfont_converter.py` | Already converts SF2→SF3 |
+| **NO CHANGE** | Dockerfile | Already has `libfluidsynth3`, `fluidsynth` CLI |
+
+---
+
+## 4. API Signature Mapping
+
+| Old (SpessaSynth) | New (FluidSynth WASM) | Notes |
+|---|---|---|
+| `_synthInstance.noteOn(ch, pitch, vel)` | `_fluid_synth_noteon(ptr, ch, pitch, vel)` | Direct C function |
+| `_synthInstance.noteOff(ch, pitch)` | `_fluid_synth_noteoff(ptr, ch, pitch)` | Direct C function |
+| `_synthInstance.controllerChange(ch, cc, val)` | `_fluid_synth_cc(ptr, ch, cc, val)` | Direct C function |
+| `_synthInstance.programChange(ch, prog)` | `_fluid_synth_program_change(ptr, ch, prog)` | Direct C function |
+| `_synthInstance.pitchBend(ch, val)` | `_fluid_synth_pitch_bend(ptr, ch, val)` | Direct C function |
+| `soundBankManager.addSoundBank(buf, id)` | `FS.writeFile(path, uint8arr)` + `_fluid_synth_sfload(ptr, path, 1)` | MEMFS-based |
+| `soundBankManager.soundBankList` | JS-side `_sfHandleMap` (Map) | Track manually |
+| `controllerChange(ch, 120, 0)` (all sound off) | `_fluid_synth_all_sounds_off(ptr, ch)` | Direct C function |
+| `controllerChange(ch, 123, 0)` (all notes off) | `_fluid_synth_all_notes_off(ptr, ch)` | Direct C function |
+
+---
+
+## 5. Risk Assessment
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| FluidSynth WASM CPU usage causes audio glitches | Medium | Use triple-buffered rendering at 512-sample blocks; monitor with `performance.now()` |
+| `_fluid_synth_write_float` blocks main thread | Medium | Move rendering to a separate rAF loop, not synchronized to audio callback |
+| SF3 loading latency on first load | Low | IndexedDB caching already in place; loading ≈2-5MB via MEMFS is sub-100ms |
+| CDN availability for `@enikey87/fluidsynth-emscripten` | Low | Package is 17.9MB unpacked; fallback host via jsDelivr + self-host option |
+| Backward compatibility with existing MIDI sessions | Medium | All `window.SonicSF` methods preserved with same signatures; `synthEngine` object handled correctly |
+
+---
+
+## 6. Validation
+
+```bash
+# 1. Build frontend
+cd /home/locpham/SonicForgeStudio
+cd app/static/js && npx babel app.jsx --config-file ../../babel.config.json -o app.precompiled.js
+
+# 2. Start server
+cd /home/locpham/SonicForgeStudio
+docker compose up -d
+
+# 3. Browser tests
+#   - Open DevTools → check `window.createFluidSynthModule` exists
+#   - Load app → check `SonicSF.init(audioCtx)` creates FluidSynth synth
+#   - Select SoundFont instrument → check MEMFS write + sfload succeeds
+#   - Play piano roll notes → hear authentic FluidSynth output
+#   - Play timeline → notes play with correct timing
+#   - External MIDI controller → CC, pitch bend, note on/off work
+#   - Transport stop → all notes stop immediately
+#   - Sustain pedal → notes sustain on CC 64 >= 64
+#   - Stress: play 50+ simultaneous notes → no stuck notes
+```
+
+**Server-side parity validation:**
+- Render a project with server (`/api/v1/plugins/render`)
+- Play same project in client browser
+- Compare WAV spectrograms: should be identical (same C++ FluidSynth core)
+
+---
+
+## 7. Open Questions for User
+
+1. **Self-host WASM vs CDN?** — `@enikey87/fluidsynth-emscripten` from jsDelivr (5.9MB) or serve from `app/static/` folder. CDN reduces server load but requires internet. If user wants offline-capable, suggest self-host.
+
+2. **Separate WASM file vs all-in-one?** — `libfluidsynth-2.3.0-sf3.js` (130KB) + `libfluidsynth-2.3.0-sf3.wasm` (1.7MB) allow browser to cache WASM separately. Or `libfluidsynth-2.3.0-sf3-all-in-one.js` (2.39MB) single file but no caching benefit. Recommend separate files.
+
+3. **Main-thread render vs worklet-own-synth?** — The spec's worklet-own-synth approach is theoretically ideal but complex (MIDI events + file data must cross thread boundary). Recommend v1 as main-thread render + simple bridge worklet. Can optimize later.
+

Dockerfile

@@ -19,18 +19,27 @@ RUN apt-get update && apt-get install -y \
     ffmpeg \
     libsndfile1 \
     libfluidsynth3 \
+    libcurl4 \
     build-essential \
+    fluidsynth \
+    vorbis-tools \
     && rm -rf /var/lib/apt/lists/*
 
 # Thiết lập biến môi trường hiển thị cho X11 ảo
 ENV DISPLAY=:99
 
+# Create VST3 and sample directories
+RUN mkdir -p /opt/daw_engine/vst3 /opt/daw_engine/soundfonts /opt/daw_engine/samples/pianobook
+
 WORKDIR /app
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 
 COPY . .
 
+# Copy VST3 plugins if present
+COPY ./vst_plugins/ /opt/daw_engine/vst3/
+
 # Tạo thư mục chứa file nhạc và cấp quyền ghi
 RUN mkdir -p /app/app/storage/uploads /app/app/storage/processed && chmod -R 777 /app/app/storage
 

TESTING.md

@@ -124,6 +124,169 @@ celery -A app.tasks.worker.celery_app worker --loglevel=info
 4. File sẽ download tự động
 5. Mở file bằng audio player để kiểm tra
 
+## 🎹 FluidSynth WASM Migration — Manual Test Plan
+
+### Môi trường
+- Mở DevTools Console (F12) → Tab Console (bật `Verbose` để thấy `[SonicSF]` logs)
+- Tab Network: filter `fluidsynth`, `sf3`, `.wasm`
+
+### Test A: FluidSynth WASM Load & Init
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| A1 | Mở http://localhost:8000 | Console: `[FluidSynth] Loaded from: https://cdn.jsdelivr.net/...` |
+| A2 | Kiểm tra Network tab | `.wasm` file tải thành công (status 200) |
+| A3 | Check window.__FluidSynthModuleFactory | `typeof window.__FluidSynthModuleFactory === 'function'` |
+| A4 | Tương tác với app (click vào DAW) | Console: `[SonicSF] FluidSynth WASM Engine initialized.` |
+| A5 | Kiểm tra AudioWorklet | Console: `Worklet reg success` hoặc check `audioWorklet` trong Application tab |
+
+### Test B: SoundFont Loading
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| B1 | Mở Plugin Manager → tab SoundFont | Danh sách SoundFont hiển thị |
+| B2 | Chọn 1 SoundFont instrument (vd: Piano) | Console: `[SonicSF] SoundFont loaded: <sfId>` |
+| B3 | Kiểm tra Network tab | Request `download/<sfId>` status 200 |
+| B4 | Chuyển đổi instrument khác (vd: Violin) | Console: `Bank Select + Program Change` (nếu cùng SF, không tải lại) |
+| B5 | Load SoundFont có loop samples (vd: Tremolo Strings, Pad, Synth) | loadSoundFont success, không lỗi |
+
+### Test C: Piano Roll Playback
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| C1 | Mở Piano Roll tab | Grid hiển thị notes |
+| C2 | Click vào 1 note trên grid | Note phát ra → âm thanh giống nhạc cụ thật (không phải oscillator beep) |
+| C3 | Click và kéo thả chuột trên grid → draw note mới | Âm thanh phát ngay lập tức |
+| C4 | Scroll wheel trên piano roll notes | Các note scroll qua phát âm thanh preview |
+| C5 | Vẽ note dài (full measure) | Note kéo dài đúng độ dài, không bị tắt giữa chừng |
+
+### Test D: MIDI Keyboard (Virtual & Hardware)
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| D1 | Click vào phím đàn virtual (piano keybed) | Note phát ra = âm thanh instrument đúng |
+| D2 | Kéo chuột ngang trên keybed | Các note phát liên tục, glide không bị stuck |
+| D3 | Kết nối MIDI keyboard qua WebMIDI | Console: `MIDI access granted` |
+| D4 | Nhấn phím trên MIDI keyboard | Note phát ra ngay, không delay |
+| D5 | Nhả phím MIDI | Note tắt ngay (không stuck, không sustain dài) |
+| D6 | Sustain pedal (CC 64) | Nhấn pedal → notes sustain; nhả → notes release |
+| D7 | Pitch bend wheel | Cao độ thay đổi real-time |
+| D8 | Modulation wheel (CC 1) | Âm thanh thay đổi (nếu instrument hỗ trợ) |
+
+### Test E: Timeline Playback (MIDI Tracks)
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| E1 | Tạo track MIDI mới | Track được tạo |
+| E2 | Gán SoundFont instrument cho track | Console log bank/program change |
+| E3 | Thêm MIDI notes vào track, click Play | Notes phát đúng pitch, đúng thời điểm, đúng instrument |
+| E4 | Click Pause → Play | Nhạc tiếp tục từ vị trí pause |
+| E5 | Click Stop | Tất cả notes tắt ngay lập tức |
+| E6 | Seek playhead → Play | Play từ vị trí mới, notes cũ tắt |
+| E7 | Set loop region → Play | Loop playback hoạt động |
+| E8 | Chuyển track instrument khác → Play | Âm thanh thay đổi theo instrument mới |
+
+### Test F: Tremolo/Sustain/Loop Instrument Stress Test
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| F1 | Chọn Tremolo Strings (GM#44) | Load SF thành công |
+| F2 | Play note → nhanh chóng NoteOff | **QUAN TRỌNG**: Note tắt ngay, không bị stuck loop |
+| F3 | Play nhiều note liên tiếp (staccato) | Mỗi note tắt hẳn trước khi note kế phát |
+| F4 | Chọn Saxophone (GM#65-67) | Load SF thành công |
+| F5 | Play note giữ 3s → NoteOff | Saxophone release envelope chạy đúng, không stuck |
+| F6 | Chọn Pad/Synth (GM#88-95) | Các instrument loop dài không bị stuck |
+| F7 | Play 10+ notes cùng lúc → Stop All | Tất cả notes tắt ngay |
+| F8 | **So sánh**: Test F1-F7 cũ: SpessaSynth bị stuck notes cần CC120+noteOn+post. FluidSynth WASM: chỉ cần noteOff thường. | FluidSynth handle loop Gen 54 đúng spec |
+
+### Test G: Multi-SoundFont Switching
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| G1 | Load SoundFont A (vd: GeneralUser) | Handle ID log |
+| G2 | Chuyển track sang instrument từ SF A | SF A active |
+| G3 | Tạo track 2, load SoundFont B (vd: SGM) | SF B load vào MEMFS |
+| G4 | Play track 1 (SF A) + track 2 (SF B) | Cả 2 soundfont phát đồng thời, mỗi track instrument đúng |
+| G5 | Unload SF A, load SF C | SF A đã unload, SF C active |
+
+### Test H: Transport Controls
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| H1 | Đang play → click Stop | Console: `FluidSynth: All notes stopped.` |
+| H2 | Play với nhiều notes đang vang → Stop | Âm thanh tắt ngay lập tức (CC 120 all sound off) |
+| H3 | Play → Pause → Seek → Play | Seek không bị stuck notes |
+| H4 | Play → Reload trang | Audio context mới, FluidSynth init lại |
+
+### Test I: Fallback Behavior
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| I1 | Chặn CDN request (DevTools → Network → Offline) | `fluidsynthLoader.js` detect localhost → vẫn dùng CDN? Set `window.__FLUIDSYNTH_CDN` = null |
+| I2 | Nếu FluidSynth init fail | Console: `FluidSynth init failed`. Fallback oscillator hoạt động (âm beep) |
+| I3 | Nếu loadSoundFont fail (network down) | Console: `SoundFont not found`. Fallback oscillator cho note preview |
+
+### Test J: Memory & Performance
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| J1 | Load SF lần đầu | Network download + MEMFS write + sfload |
+| J2 | Load lại SF lần 2 (đã cache IndexedDB) | `_sfHandleMap.has(sfId)` → true, skip download |
+| J3 | Check Performance tab (DevTools) | `_fluid_synth_write_float` không block main thread > 5ms |
+| J4 | Play liên tục 5 phút | Không memory leak, không audio glitch |
+| J5 | Load SF 3-4MB (SGM v2.01) | MEMFS write + sfload < 500ms |
+
+### Test K: Audio Parity (Client vs Server)
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| K1 | Tạo project với MIDI notes + SoundFont | Client preview âm thanh |
+| K2 | Export WAV server-side (Render) | Server dùng pyfluidsynth (C++ core) |
+| K3 | **So sánh** WAV export vs Client preview | Giống nhau 100% (cùng FluidSynth engine) |
+| K4 | Test với SF3 files | Cả client (FluidSynth WASM) và server (pyfluidsynth) đều xử lý SF3 |
+
+### Test L: Regression — Tính năng không thay đổi
+
+| Step | Action | Expected Result |
+|------|--------|----------------|
+| L1 | AI track generation | `applyAITrackInstrument` works → bank/program change |
+| L2 | Audio file playback | Không ảnh hưởng (vẫn dùng AudioEngine cũ) |
+| L3 | VST instrument tracks | Không ảnh hưởng (dùng VST engine riêng) |
+| L4 | Upload/download file | Không thay đổi |
+| L5 | Multi-track mix | Không thay đổi |
+
+### Test Environment Setup
+
+```bash
+# 1. Start server
+cd /home/locpham/SonicForgeStudio
+docker compose up -d --build
+
+# 2. Clear browser cache trước khi test lần đầu (cache-bust version đã update)
+# Chrome: DevTools → Network → Disable cache (khi DevTools mở)
+
+# 3. Kiểm tra console logs
+# Mở DevTools Console, filter: [SonicSF] [FluidSynth]
+
+# 4. Force re-download SF (xóa IndexedDB cache nếu cần)
+# Application → IndexedDB → DAW_SoundFont_Cache → Clear
+```
+
+### Checklist
+
+- [ ] A1-A5: FluidSynth WASM load + init
+- [ ] B1-B5: SoundFont load + switch (nhiều SF)
+- [ ] C1-C5: Piano roll note play
+- [ ] D1-D8: MIDI keyboard (virtual + hardware)
+- [ ] E1-E8: Timeline playback
+- [ ] F1-F8: **Tremolo/Sustain loop stress** — key test
+- [ ] G1-G5: Multi-SoundFont switching
+- [ ] H1-H4: Transport controls (stop, seek)
+- [ ] I1-I3: Fallback oscillator
+- [ ] J1-J5: Memory & performance
+- [ ] K1-K4: Audio parity client vs server
+- [ ] L1-L5: Regression (features không thay đổi)
+
 ## 🐛 Known Issues
 
 ### Docker Environment

app/api/v1/plugins.py

@@ -1,10 +1,13 @@
 import os, uuid, json, tempfile
-from fastapi import APIRouter, HTTPException, Depends, UploadFile, File
+from fastapi import APIRouter, HTTPException, Depends, UploadFile, File, BackgroundTasks
+from fastapi.responses import FileResponse
 from pydantic import BaseModel
 from typing import Optional, Any
 from app.config import settings
 from app.core.vst_engine import PluginManager, HAS_PEDALBOARD, HAS_PYFLUIDSYNTH
 from app.core.render_engine import PythonRenderEngine
+from app.core.soundfont_inspector import SoundFontInspector
+from app.core.soundfont_converter import SoundFontConverter
 from app.api.v1.auth import get_current_user
 
 router = APIRouter()
@@ -12,6 +15,16 @@ router = APIRouter()
 UPLOAD_SF_DIR = os.path.join(settings.STORAGE_DIR, "soundfonts")
 os.makedirs(UPLOAD_SF_DIR, exist_ok=True)
 
+SYSTEM_SF_DIR = "/opt/daw_engine/soundfonts"
+
+_inspector = None
+
+def get_inspector():
+    global _inspector
+    if _inspector is None:
+        _inspector = SoundFontInspector(system_sf_dir=SYSTEM_SF_DIR, upload_sf_dir=UPLOAD_SF_DIR)
+    return _inspector
+
 
 @router.get("/available")
 async def list_plugins(current_user: dict = Depends(get_current_user)):
@@ -35,6 +48,14 @@ async def list_default_soundfonts():
     return result
 
 
+@router.get("/soundfonts/catalog")
+async def soundfont_catalog(current_user: dict = Depends(get_current_user)):
+    inspector = get_inspector()
+    full_catalog = inspector.get_catalog()
+    condensed_catalog = inspector.get_condensed_catalog_summary()
+    return {"full_catalog": full_catalog, "condensed_catalog": condensed_catalog}
+
+
 @router.get("/soundfont-instruments/{sf_id}")
 async def list_soundfont_instruments(sf_id: str, current_user: dict = Depends(get_current_user)):
     pm = PluginManager(upload_sf_dir=UPLOAD_SF_DIR)
@@ -45,6 +66,7 @@ async def list_soundfont_instruments(sf_id: str, current_user: dict = Depends(ge
 @router.post("/upload-soundfont")
 async def upload_soundfont(
     file: UploadFile = File(...),
+    background_tasks: BackgroundTasks = None,
     current_user: dict = Depends(get_current_user)
 ):
     if not (file.filename and (file.filename.endswith(".sf2") or file.filename.endswith(".sf3"))):
@@ -69,6 +91,11 @@ async def upload_soundfont(
         import json
         json.dump({"original_name": file.filename, "uuid": file_uuid, "file": file_id}, f)
 
+    inspector = get_inspector()
+    inspector.invalidate_catalog_cache()
+    if background_tasks:
+        background_tasks.add_task(inspector.generate_full_catalog)
+
     return {"id": file_id, "name": file.filename, "path": dest_path, "size_bytes": len(contents)}
 
 
@@ -76,14 +103,16 @@ async def upload_soundfont(
 async def delete_soundfont(sf_id: str, current_user: dict = Depends(get_current_user)):
     base_id = sf_id.replace("sf_", "")
     deleted = False
-    for d in [UPLOAD_SF_DIR, os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "static", "soundfonts")]:
+    for d in [UPLOAD_SF_DIR, os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "static", "soundfonts"), SYSTEM_SF_DIR]:
         if not os.path.isdir(d):
             continue
         for f in os.listdir(d):
             if os.path.splitext(f)[0] == base_id:
+                # Skip system dir — only allow deleting uploads
+                if d == SYSTEM_SF_DIR:
+                    raise HTTPException(status_code=403, detail="System soundfonts cannot be deleted via this endpoint")
                 path = os.path.join(d, f)
                 os.remove(path)
-                # Remove associated .meta file
                 meta_path = os.path.join(d, os.path.splitext(f)[0] + ".meta")
                 if os.path.isfile(meta_path):
                     os.remove(meta_path)
@@ -93,9 +122,26 @@ async def delete_soundfont(sf_id: str, current_user: dict = Depends(get_current_
             break
     if not deleted:
         raise HTTPException(status_code=404, detail="SoundFont not found")
+    inspector = get_inspector()
+    inspector.invalidate_catalog_cache()
     return {"deleted": True, "sf_id": sf_id}
 
 
+@router.get("/soundfonts/download/{sf_id}")
+async def download_soundfont_asset(sf_id: str):
+    clean_id = sf_id.replace("sf_", "") if sf_id.startswith("sf_") else sf_id
+    for base_dir in [UPLOAD_SF_DIR, SYSTEM_SF_DIR]:
+        if not os.path.isdir(base_dir):
+            continue
+        for ext in [".sf2", ".sf3"]:
+            for fname in os.listdir(base_dir):
+                fbase, fext = os.path.splitext(fname)
+                if fext.lower() == ext and fbase.lower() == clean_id.lower():
+                    full = os.path.join(base_dir, fname)
+                    return FileResponse(full, media_type="application/octet-stream", filename=f"soundfont{ext}")
+    raise HTTPException(status_code=404, detail="SoundFont asset not found")
+
+
 class RenderRequest(BaseModel):
     project_json: dict
     output_filename: Optional[str] = "render_output.wav"

app/api/v1/projects.py

@@ -97,6 +97,16 @@ def upgrade_project_json_if_needed(project_data: dict) -> dict:
 def validate_project_data(data_json: str) -> str:
     try:
         data = json.loads(data_json)
+        if "project_id" not in data:
+            data["project_id"] = "temp_legacy_" + str(int(time.time()))
+        # Strip null synth_engine from tracks (breaks schema validation)
+        for session_key in ["main_session"] + [k for k in data.get("section_store", {})]:
+            session = data.get(session_key)
+            if not session:
+                continue
+            for track in session.get("tracks", []):
+                if "synth_engine" in track and track["synth_engine"] is None:
+                    del track["synth_engine"]
         if "main_session" not in data:
             data = upgrade_project_json_if_needed(data)
             data_json = json.dumps(data)

app/core/render_engine.py

@@ -1,4 +1,4 @@
-import os
+import os, logging
 import numpy as np
 import soundfile as sf
 import scipy.signal as signal
@@ -6,10 +6,49 @@ from app.config import settings
 from app.core.vst_engine import (
     render_midi_events_to_audio,
     PluginManager,
+    DecentSamplerManager,
     HAS_PEDALBOARD,
     HAS_PYFLUIDSYNTH,
 )
 
+logger = logging.getLogger(__name__)
+
+UPLOAD_SF_DIR = os.path.join(settings.STORAGE_DIR, "soundfonts")
+SYSTEM_SF_DIR = "/opt/daw_engine/soundfonts"
+
+SYS_SOUNDFONTS = [
+    ("GeneralUser_GS.sf2", "GeneralUser GS"),
+    ("SGM_v2.01.sf2", "SGM v2.01"),
+    ("SGM-V2.01.sf2", "SGM v2.01"),
+]
+
+def _find_sf2_path(sf_id: str) -> str:
+    clean_id = sf_id.replace("sf_", "") if sf_id.startswith("sf_") else sf_id
+    clean_lower = clean_id.lower()
+    sf_lower = sf_id.lower()
+    for base_dir in [UPLOAD_SF_DIR, SYSTEM_SF_DIR]:
+        if not os.path.isdir(base_dir):
+            continue
+        for fname in os.listdir(base_dir):
+            fbase, fext = os.path.splitext(fname)
+            if fext.lower() in (".sf2", ".sf3") and (fbase.lower() == clean_lower or fbase.lower() == sf_lower):
+                return os.path.join(base_dir, fname)
+    static_dir = os.path.join(settings.APP_DIR, "static", "soundfonts")
+    if os.path.isdir(static_dir):
+        for fname in os.listdir(static_dir):
+            fbase, fext = os.path.splitext(fname)
+            if fext.lower() in (".sf2", ".sf3") and (fbase.lower() == clean_lower or fbase.lower() == sf_lower):
+                return os.path.join(static_dir, fname)
+    return ""
+
+def _find_default_sf2() -> str:
+    for sf_name, _ in SYS_SOUNDFONTS:
+        for base_dir in [SYSTEM_SF_DIR, UPLOAD_SF_DIR]:
+            p = os.path.join(base_dir, sf_name)
+            if os.path.exists(p):
+                return p
+    return ""
+
 if HAS_PEDALBOARD:
     try:
         from pedalboard import Pedalboard, Gain, Chorus, Reverb
@@ -51,10 +90,24 @@ class PythonRenderEngine:
     def render_session_container(self, session: dict, section_store: dict, bpm: float, time_sig_num: int, total_samples: int) -> np.ndarray:
         session_buffer = np.zeros((2, total_samples), dtype=np.float32)
 
+        _channel_counter = 0
+
         for track in session.get("tracks", []):
             track_type = track.get("type", "AUDIO")
             track_buffer = np.zeros((2, total_samples), dtype=np.float32)
 
+            # Parse synth_engine struct (Task C) — fall back to flat fields
+            se = track.get("synth_engine", {}) or {}
+            instrument_id = se.get("plugin_id") or track.get("instrument_id", "") or track.get("instrument", "")
+            instrument_source = se.get("type") or track.get("instrument_source", "soundfont")
+            soundfont_bank = se.get("soundfont_bank") if se.get("soundfont_bank") is not None else track.get("soundfont_bank", 0)
+            soundfont_program = se.get("soundfont_program") if se.get("soundfont_program") is not None else track.get("soundfont_program", 0)
+            soundfont_id = se.get("soundfont_id") or track.get("soundfont_id", "")
+            is_percussion = track.get("is_percussion", False) or (soundfont_bank == 128)
+            midi_channel = 9 if is_percussion else (_channel_counter % 9)
+            if not is_percussion:
+                _channel_counter += 1
+
             for item in track.get("items", []):
                 start_sample = self.bars_to_samples(item["start_bar"], bpm, time_sig_num)
                 dur_samples = self.bars_to_samples(item["duration_bars"], bpm, time_sig_num)
@@ -120,15 +173,43 @@ class PythonRenderEngine:
                     
                     if midi_events:
                         try:
-                            instrument_id = track.get("instrument", "")
                             plugin_mgr = PluginManager()
                             vst = plugin_mgr.load_vst(instrument_id) if instrument_id else None
 
-                            if vst and HAS_PEDALBOARD:
+                            if instrument_source == "pianobook":
+                                dspreset_path = track.get("dspreset_path", "")
+                                if dspreset_path and os.path.exists(dspreset_path) and HAS_PEDALBOARD:
+                                    from pedalboard import Pedalboard
+                                    ds_manager = DecentSamplerManager()
+                                    try:
+                                        vst = ds_manager.create_decent_sampler_instance(dspreset_path)
+                                        midi_messages = PluginManager.midi_events_to_messages(
+                                            midi_events, bpm, self.sample_rate
+                                        )
+                                        total_needed = 0
+                                        for ev in midi_events:
+                                            end_sec = (ev.get("start_beat", 0) + ev.get("duration_beats", 1)) * (60.0 / bpm)
+                                            dur_samples = int(end_sec * self.sample_rate)
+                                            if dur_samples > total_needed:
+                                                total_needed = dur_samples
+                                        total_needed = max(total_needed, 1024)
+                                        silent = np.zeros((2, total_needed), dtype=np.float32)
+                                        board = Pedalboard([vst])
+                                        synth_buffer = board(silent, sample_rate=self.sample_rate, midi_messages=midi_messages)
+                                    except Exception as e:
+                                        logger.warning(f"[RenderEngine] DecentSampler/Pianobook error: {e}")
+                                        synth_buffer = render_midi_events_to_audio(
+                                            midi_events=midi_events, sr=self.sample_rate, bpm=bpm, instrument='synth'
+                                        )
+                                else:
+                                    synth_buffer = render_midi_events_to_audio(
+                                        midi_events=midi_events, sr=self.sample_rate, bpm=bpm, instrument='synth'
+                                    )
+                            elif vst and HAS_PEDALBOARD:
                                 from pedalboard import Pedalboard
-                                # Convert MIDI events with precise sample offset
                                 midi_messages = PluginManager.midi_events_to_messages(
-                                    midi_events, bpm, self.sample_rate
+                                    midi_events, bpm, self.sample_rate,
+                                    bank=soundfont_bank, program=soundfont_program
                                 )
                                 total_needed = 0
                                 for ev in midi_events:
@@ -140,44 +221,59 @@ class PythonRenderEngine:
                                 silent = np.zeros((2, total_needed), dtype=np.float32)
                                 board = Pedalboard([vst])
                                 synth_buffer = board(silent, sample_rate=self.sample_rate, midi_messages=midi_messages)
-                            elif instrument_id and instrument_id.startswith("sf_"):
-                                sf_path = os.path.join(
-                                    os.path.dirname(os.path.dirname(__file__)), "static", "soundfonts",
-                                    instrument_id.replace("sf_", "") + ".sf2"
-                                )
-                                if os.path.exists(sf_path) and HAS_PYFLUIDSYNTH:
-                                    import fluidsynth
-                                    fl = fluidsynth.FluidSynth(sample_rate=self.sample_rate, gain=0.5)
-                                    fid = fl.sfload(sf_path)
-                                    fl.program_select(0, fid, 0, 0)
+                            elif instrument_id and (instrument_id.startswith("sf_") or soundfont_id):
+                                sf_path = _find_sf2_path(soundfont_id or instrument_id)
+                                # 3-level fallback: selected SF → default SF → oscillator synth
+                                if not sf_path or not os.path.exists(sf_path) or not HAS_PYFLUIDSYNTH:
+                                    if not sf_path or not os.path.exists(sf_path):
+                                        logger.warning(f"[RenderEngine] SoundFont not found for {soundfont_id or instrument_id}, trying default")
+                                    sf_path = _find_default_sf2() if HAS_PYFLUIDSYNTH else ""
+
+                                if sf_path and os.path.exists(sf_path) and HAS_PYFLUIDSYNTH:
+                                    import fluidsynth as _fs
+                                    _settings = _fs.new_fluid_settings()
+                                    _fs.fluid_settings_setnum(_settings, b'synth.sample-rate', float(self.sample_rate))
+                                    _fl = _fs.new_fluid_synth(_settings)
+                                    _fid = _fs.fluid_synth_sfload(_fl, sf_path.encode("utf-8"), 1)
+                                    _fs.fluid_synth_program_select(_fl, midi_channel, _fid, soundfont_bank, soundfont_program)
                                     beat_sec = 60.0 / bpm
                                     total_sec = 0
                                     for ev in midi_events:
                                         end_sec = (ev.get("start_beat", 0) + ev.get("duration_beats", 1)) * beat_sec
                                         if end_sec > total_sec:
                                             total_sec = end_sec
-                                    total_samples = int((total_sec + 1.0) * self.sample_rate)
-                                    midi_data = np.zeros((2, total_samples), dtype=np.float32)
-                                    for ev in midi_events:
+                                    sf_total_samples = int((total_sec + 1.0) * self.sample_rate)
+                                    midi_data = np.zeros((2, sf_total_samples), dtype=np.float32)
+                                    _cursor = 0
+                                    for ev in sorted(midi_events, key=lambda e: e.get("start_beat", 0)):
                                         note = ev.get("note", 60)
                                         velocity = ev.get("velocity", 100)
                                         start_beat = ev.get("start_beat", 0.0)
                                         dur_beats = ev.get("duration_beats", 1.0)
                                         start_sec = start_beat * beat_sec
                                         dur_sec = dur_beats * beat_sec
-                                        fl.noteon(0, note, velocity)
                                         start_s = int(start_sec * self.sample_rate)
                                         dur_s = int(dur_sec * self.sample_rate)
-                                        block = fl.get_samples(int(dur_s)) if hasattr(fl, 'get_samples') else np.zeros((2, dur_s), dtype=np.float32)
-                                        fl.noteoff(0, note)
-                                        if block.shape[1] > 0:
-                                            end_s = min(start_s + block.shape[1], total_samples)
-                                            actual = end_s - start_s
-                                            if actual > 0:
-                                                midi_data[:, start_s:end_s] += block[:, :actual]
+                                        # Advance synth time by rendering silence
+                                        if start_s > _cursor:
+                                            gap = start_s - _cursor
+                                            _fs.fluid_synth_write_s16_stereo(_fl, gap)
+                                            _cursor = start_s
+                                        # Start note
+                                        _fs.fluid_synth_noteon(_fl, midi_channel, note, min(velocity, 127))
+                                        block_s16 = _fs.fluid_synth_write_s16_stereo(_fl, dur_s)
+                                        _fs.fluid_synth_noteoff(_fl, midi_channel, note)
+                                        block = block_s16.astype(np.float32).reshape(-1, 2).T / 32768.0
+                                        end_s = min(_cursor + block.shape[1], sf_total_samples)
+                                        actual = end_s - _cursor
+                                        if actual > 0 and block.shape[1] > 0:
+                                            midi_data[:, _cursor:end_s] += block[:, :actual]
+                                        _cursor = end_s
                                     synth_buffer = midi_data
-                                    fl.delete()
+                                    _fs.delete_fluid_synth(_fl)
                                 else:
+                                    if not HAS_PYFLUIDSYNTH:
+                                        logger.warning("[RenderEngine] pyfluidsynth not available, falling back to oscillator synth")
                                     synth_buffer = render_midi_events_to_audio(
                                         midi_events=midi_events, sr=self.sample_rate, bpm=bpm, instrument='synth'
                                     )

app/core/soundfont_converter.py

@@ -0,0 +1,251 @@
+import os
+import struct
+import subprocess
+import logging
+import wave
+
+logger = logging.getLogger(__name__)
+
+SF_TARGET_DIRS = [
+    "/opt/daw_engine/soundfonts",
+]
+
+
+def _find_chunk(data, chunk_id, offset=12, max_size=0):
+    pos = offset
+    end = len(data) if max_size == 0 else offset + max_size
+    while pos + 8 <= end:
+        ck_id = data[pos:pos + 4]
+        ck_size = struct.unpack("<I", data[pos + 4:pos + 8])[0]
+        if ck_id == chunk_id:
+            return (pos, ck_id, ck_size, pos + 8)
+        if ck_id == b"LIST" and pos + 12 <= end:
+            list_type = data[pos + 8:pos + 12]
+            # Check if we're looking for a specific list type
+            if chunk_id == b"smpl" and list_type == b"sdta":
+                inner = _find_chunk_in_list(data, chunk_id, pos + 12, ck_size - 4)
+                if inner:
+                    return inner
+            elif chunk_id == b"LIST":
+                # When searching for LIST by type, check if it's sdta
+                pass
+            else:
+                inner = _find_chunk_in_list(data, chunk_id, pos + 12, ck_size - 4)
+                if inner:
+                    return inner
+        pos += 8 + ck_size
+        if ck_size % 2 == 1:
+            pos += 1
+    return None
+
+
+def _find_list_of_type(data, list_type_id, offset=12):
+    pos = offset
+    while pos + 12 <= len(data):
+        ck_id = data[pos:pos + 4]
+        ck_size = struct.unpack("<I", data[pos + 4:pos + 8])[0]
+        if ck_id == b"LIST":
+            form_type = data[pos + 8:pos + 12]
+            if form_type == list_type_id:
+                return (pos, ck_id, ck_size, pos + 12)
+        pos += 8 + ck_size
+        if ck_size % 2 == 1:
+            pos += 1
+    return None
+
+
+def _find_chunk_in_list(data, chunk_id, list_data_offset, list_data_size):
+    pos = list_data_offset
+    end = list_data_offset + list_data_size
+    while pos + 8 <= end:
+        ck_id = data[pos:pos + 4]
+        ck_size = struct.unpack("<I", data[pos + 4:pos + 8])[0]
+        if ck_id == chunk_id:
+            return (pos, ck_id, ck_size, pos + 8)
+        pos += 8 + ck_size
+        if ck_size % 2 == 1:
+            pos += 1
+    return None
+
+
+def _update_size(data, offset, new_size):
+    return data[:offset] + struct.pack("<I", new_size) + data[offset + 4:]
+
+
+class SoundFontConverter:
+    def __init__(self, target_dirs=None):
+        self.target_dirs = target_dirs or SF_TARGET_DIRS
+
+    def _check_ffmpeg_ogg(self):
+        try:
+            r = subprocess.run(["ffmpeg", "-encoders"], capture_output=True, text=True, timeout=5)
+            return "libvorbis" in r.stdout
+        except Exception:
+            return False
+
+    def _sf2_to_sf3_python(self, sf2_path: str, sf3_path: str) -> bool:
+        has_ogg = self._check_ffmpeg_ogg()
+        if not has_ogg:
+            logger.warning("ffmpeg with libvorbis not available, cannot convert to SF3")
+            return False
+
+        try:
+            with open(sf2_path, "rb") as f:
+                data = f.read()
+        except Exception as e:
+            logger.error(f"Cannot read {sf2_path}: {e}")
+            return False
+
+        if len(data) < 12 or data[:4] != b"RIFF" or data[8:12] != b"sfbk":
+            logger.warning("Not a valid SF2 file")
+            return False
+
+        # Find smpl chunk recursively
+        smpl = _find_chunk(data, b"smpl")
+        if smpl is None:
+            logger.warning("No smpl chunk found in SF2")
+            return False
+
+        smpl_head_off, _, smpl_old_size, smpl_data_off = smpl
+        sample_data = data[smpl_data_off:smpl_data_off + smpl_old_size]
+
+        if len(sample_data) < 16:
+            logger.warning("Sample data too small")
+            return False
+
+        tmp_wav = sf3_path + ".tmp.wav"
+        tmp_ogg = sf3_path + ".tmp.ogg"
+
+        try:
+            # Write samples as WAV
+            with open(tmp_wav, "wb") as fw:
+                with wave.open(fw, "wb") as w:
+                    w.setnchannels(1)
+                    w.setsampwidth(2)
+                    w.setframerate(44100)
+                    w.writeframes(sample_data)
+
+            # Compress to Ogg Vorbis
+            subprocess.run([
+                "ffmpeg", "-y", "-i", tmp_wav,
+                "-c:a", "libvorbis", "-q:a", "3",
+                "-f", "ogg", tmp_ogg
+            ], capture_output=True, timeout=600, check=True)
+
+            with open(tmp_ogg, "rb") as fo:
+                ogg_data = fo.read()
+
+            compression = (1 - len(ogg_data) / max(len(sample_data), 1)) * 100
+            logger.info(f"Compressed {len(sample_data)} -> {len(ogg_data)} bytes ({compression:.0f}%)")
+
+            ogg_padded = ogg_data if len(ogg_data) % 2 == 0 else ogg_data + b"\x00"
+            new_smpl_size = len(ogg_data)
+            old_padded = smpl_old_size + (1 if smpl_old_size % 2 == 1 else 0)
+            new_padded = len(ogg_padded)
+            delta = new_padded - old_padded
+
+            # Rebuild file: replace smpl chunk and update all sizes
+            out = bytearray()
+            out.extend(data[:smpl_head_off])           # up to smpl chunk header
+            out.extend(struct.pack("<I", new_smpl_size))  # new smpl size
+            out.extend(ogg_padded)                     # compressed data (even-padded)
+            out.extend(data[smpl_head_off + 8 + old_padded:])  # rest of file
+
+            data_out = bytes(out)
+
+            # Find sdta LIST and update its size
+            sdta = _find_list_of_type(data_out, b"sdta", 12)
+            if sdta:
+                lh_off, _, lh_size, ld_off = sdta
+                data_out = _update_size(data_out, lh_off + 4, lh_size + delta)
+
+            # Update RIFF root size
+            old_riff_size = struct.unpack("<I", data_out[4:8])[0]
+            new_total = len(data_out) - 8
+            data_out = _update_size(data_out, 4, new_total)
+
+            with open(sf3_path, "wb") as fout:
+                fout.write(bytes(data_out))
+
+            # Validate: check that RIFF size matches actual size
+            written = os.path.getsize(sf3_path)
+            parsed_riff = struct.unpack("<I", data_out[4:8])[0]
+            if parsed_riff != written - 8:
+                logger.warning(f"Size mismatch: RIFF says {parsed_riff}, actual is {written - 8}")
+                return False
+
+            return True
+
+        except subprocess.TimeoutExpired:
+            logger.error("Ogg conversion timed out")
+            return False
+        except Exception as e:
+            logger.error(f"Conversion error: {e}")
+            import traceback
+            traceback.print_exc()
+            return False
+        finally:
+            for p in [tmp_wav, tmp_ogg]:
+                try:
+                    if os.path.exists(p):
+                        os.remove(p)
+                except Exception:
+                    pass
+
+    @staticmethod
+    def _find_sf3_converter():
+        for exe in ["fluidsynth", "mscore"]:
+            try:
+                subprocess.run([exe, "--help"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=2.0)
+                return exe
+            except (FileNotFoundError, subprocess.TimeoutExpired):
+                continue
+        return "python"
+
+    def convert_sf2_to_sf3(self, sf2_path: str) -> str:
+        if not os.path.exists(sf2_path):
+            raise FileNotFoundError(f"Source SF2 file not found: {sf2_path}")
+
+        sf3_path = os.path.splitext(sf2_path)[0] + ".sf3"
+
+        if os.path.exists(sf3_path) and os.path.getmtime(sf3_path) >= os.path.getmtime(sf2_path):
+            logger.info(f"SF3 already up-to-date: {sf3_path}")
+            return sf3_path
+
+        converter = self._find_sf3_converter()
+        try:
+            logger.info(f"Converting '{sf2_path}' -> '{sf3_path}' using {converter}...")
+            if converter == "fluidsynth":
+                converter = "python"
+
+            if converter == "mscore":
+                cmd = ["mscore", "-o", sf3_path, sf2_path]
+                result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+                if result.returncode == 0 and os.path.exists(sf3_path):
+                    logger.info(f"Created SF3 via mscore: {sf3_path} ({os.path.getsize(sf3_path)/1024/1024:.1f}MB)")
+                    return sf3_path
+                converter = "python"
+
+            if converter == "python":
+                if self._sf2_to_sf3_python(sf2_path, sf3_path) and os.path.exists(sf3_path):
+                    size_mb = os.path.getsize(sf3_path) / (1024 * 1024)
+                    logger.info(f"Created SF3: {sf3_path} ({size_mb:.2f} MB)")
+                    return sf3_path
+                logger.warning(f"Python converter failed for {sf2_path}, returning SF2 path")
+                return sf2_path
+
+            return sf2_path
+        except subprocess.TimeoutExpired:
+            logger.error(f"Conversion timed out for {sf2_path}")
+            return sf2_path
+        except Exception as e:
+            logger.error(f"Error converting {sf2_path}: {e}")
+            return sf2_path
+
+    def batch_convert_all(self):
+        for sdir in self.target_dirs:
+            if not os.path.isdir(sdir):
+                continue
+            for fname in sorted(os.listdir(sdir)):
+                if fname.lower().endswith(".sf2"):
+                    self.convert_sf2_to_sf3(os.path.join(sdir, fname))

app/core/soundfont_inspector.py

@@ -0,0 +1,155 @@
+import os
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+try:
+    from sf2utils.sf2parse import Sf2File
+    HAS_SF2UTILS = True
+except ImportError:
+    HAS_SF2UTILS = False
+
+GM_CATEGORIES = [
+    ("Piano", range(0, 8)),
+    ("Chromatic Percussion", range(8, 16)),
+    ("Organ", range(16, 24)),
+    ("Guitar", range(24, 32)),
+    ("Bass", range(32, 40)),
+    ("Strings", range(40, 48)),
+    ("Ensemble", range(48, 56)),
+    ("Brass", range(56, 64)),
+    ("Reed", range(64, 72)),
+    ("Pipe", range(72, 80)),
+    ("Synth Lead", range(80, 90)),
+    ("Synth Pad", range(90, 104)),
+]
+
+MAX_CONDENSED_ENTRIES = 50
+
+
+class SoundFontInspector:
+    def __init__(self, system_sf_dir="/opt/daw_engine/soundfonts", upload_sf_dir=None):
+        self.system_sf_dir = system_sf_dir
+        self.upload_sf_dir = upload_sf_dir
+        self._catalog_cache = None
+
+    def invalidate_catalog_cache(self):
+        self._catalog_cache = None
+
+    def inspect_sf2_file(self, filepath: str) -> dict:
+        if not HAS_SF2UTILS:
+            logger.warning("sf2utils not installed, cannot inspect .sf2 files")
+            return {}
+        if not os.path.exists(filepath):
+            return {}
+
+        try:
+            sf_name = os.path.basename(filepath)
+            sf_id = os.path.splitext(sf_name)[0].lower()
+
+            instruments = []
+            with open(filepath, 'rb') as f:
+                sf2 = Sf2File(f)
+                for preset in sf2.presets:
+                    name = preset.name.strip()
+                    if name == "EOP" or (preset.bank == 128 and preset.preset == 127):
+                        continue
+                    instruments.append({
+                        "bank": preset.bank,
+                        "program": preset.preset,
+                        "name": name,
+                        "is_percussion": (preset.bank == 128)
+                    })
+
+            return {
+                "soundfont_id": sf_id,
+                "filename": sf_name,
+                "total_instruments": len(instruments),
+                "instruments": instruments
+            }
+        except Exception as e:
+            logger.warning(f"Skipping corrupted .sf2 file {filepath}: {e}")
+            return {}
+
+    def _scan_directory(self, directory: str) -> dict:
+        catalog = {}
+        if not os.path.isdir(directory):
+            return catalog
+        for fname in os.listdir(directory):
+            if not fname.lower().endswith(('.sf2', '.sf3')):
+                continue
+            full_path = os.path.join(directory, fname)
+            sf_info = self.inspect_sf2_file(full_path)
+            if sf_info and sf_info.get("soundfont_id"):
+                catalog[sf_info["soundfont_id"]] = sf_info
+        return catalog
+
+    def generate_full_catalog(self, output_json_path: str = None) -> dict:
+        catalog = {}
+        catalog.update(self._scan_directory(self.system_sf_dir))
+        if self.upload_sf_dir and os.path.isdir(self.upload_sf_dir):
+            catalog.update(self._scan_directory(self.upload_sf_dir))
+
+        if output_json_path:
+            os.makedirs(os.path.dirname(output_json_path), exist_ok=True)
+            with open(output_json_path, 'w', encoding='utf-8') as f:
+                json.dump(catalog, f, ensure_ascii=False, indent=2)
+
+        self._catalog_cache = catalog
+        return catalog
+
+    def get_catalog(self) -> dict:
+        if self._catalog_cache is not None:
+            return self._catalog_cache
+        return self.generate_full_catalog()
+
+    def get_condensed_catalog_summary(self) -> dict:
+        catalog = self.get_catalog()
+        condensed = {}
+        for sf_id, sf_info in catalog.items():
+            instruments = sf_info.get("instruments", [])
+            if not instruments:
+                continue
+
+            selected = []
+            used_programs = set()
+            for cat_name, prog_range in GM_CATEGORIES:
+                cat_members = [
+                    inst for inst in instruments
+                    if inst["program"] in prog_range and not inst["is_percussion"]
+                ]
+                if cat_members:
+                    representative = cat_members[0]
+                    key = (representative["program"], representative["bank"])
+                    if key not in used_programs:
+                        used_programs.add(key)
+                        selected.append(representative)
+
+            drum_kits = [inst for inst in instruments if inst["is_percussion"]]
+            for dk in drum_kits[:3]:
+                key = (dk["program"], dk["bank"])
+                if key not in used_programs:
+                    used_programs.add(key)
+                    selected.append(dk)
+
+            if len(selected) > MAX_CONDENSED_ENTRIES:
+                selected = selected[:MAX_CONDENSED_ENTRIES]
+
+            condensed[sf_id] = {
+                "soundfont_id": sf_info["soundfont_id"],
+                "filename": sf_info["filename"],
+                "total_instruments": sf_info["total_instruments"],
+                "condensed_count": len(selected),
+                "instruments": selected
+            }
+        return condensed
+
+    def format_condensed_for_prompt(self) -> str:
+        condensed = self.get_condensed_catalog_summary()
+        lines = []
+        for sf_id, info in condensed.items():
+            lines.append(f"SoundFont ID: '{sf_id}' (File: {info['filename']}):")
+            for inst in info["instruments"]:
+                lines.append(f"  - {inst['name']}: bank={inst['bank']}, program={inst['program']}")
+        return "\n".join(lines)

app/core/vst_engine.py

@@ -163,12 +163,11 @@ class PluginManager:
         return plugins
 
     def _scan_soundfonts(self) -> list:
-        sfonts = []
-        dirs = [self.sf_dir]
+        sf_map = {}
+        dirs = [("system", self.sf_dir)]
         if self.upload_sf_dir and self.upload_sf_dir != self.sf_dir:
-            dirs.append(self.upload_sf_dir)
+            dirs.append(("upload", self.upload_sf_dir))
         
-        # Load metadata cache for upload soundfonts
         meta_cache = {}
         if self.upload_sf_dir and os.path.isdir(self.upload_sf_dir):
             for f in os.listdir(self.upload_sf_dir):
@@ -180,21 +179,28 @@ class PluginManager:
                     except Exception:
                         pass
         
-        for d in dirs:
+        for source, d in dirs:
             if not os.path.isdir(d):
                 continue
             for f in os.listdir(d):
                 if f.endswith(".sf2") or f.endswith(".sf3"):
                     base_id = os.path.splitext(f)[0]
+                    if base_id in sf_map:
+                        continue
                     meta = meta_cache.get(base_id, None)
                     if meta:
                         display_name = meta.get("original_name", f)
                     else:
-                        # Generate a friendly name from UUID: truncate to first 8 chars
                         short_id = base_id[:8] if len(base_id) > 8 else base_id
                         display_name = f"SoundFont_{short_id}"
-                    sfonts.append({"id": base_id, "name": display_name, "file": f, "display": os.path.splitext(display_name)[0][:40]})
-        return sfonts
+                    sf_map[base_id] = {
+                        "id": base_id,
+                        "name": display_name,
+                        "file": f,
+                        "display": os.path.splitext(display_name)[0][:40],
+                        "source": source
+                    }
+        return list(sf_map.values())
 
     def load_vst(self, plugin_name: str, preset_data: dict = None):
         if not HAS_PEDALBOARD:
@@ -286,11 +292,15 @@ class PluginManager:
         }
 
     @staticmethod
-    def midi_events_to_messages(midi_events: list, bpm: float, sr: int) -> list:
+    def midi_events_to_messages(midi_events: list, bpm: float, sr: int, bank: int = None, program: int = None) -> list:
         if not HAS_PEDALBOARD:
             return []
         beat_duration_sec = 60.0 / max(30.0, bpm)
         messages = []
+        if bank is not None:
+            messages.append(MidiMessage(control_change=0, value=bank, sample_offset=0))
+        if program is not None:
+            messages.append(MidiMessage(program_change=program, sample_offset=0))
         for ev in midi_events:
             note = ev.get("note", 60)
             velocity = ev.get("velocity", 100)
@@ -313,3 +323,29 @@ class PluginManager:
         if data[8:12] != b'sfbk':
             return False
         return True
+
+
+class DecentSamplerManager:
+    def __init__(self, vst_path="/opt/daw_engine/vst3/DecentSampler.vst3"):
+        self.vst_path = vst_path
+
+    def create_decent_sampler_instance(self, dspreset_path: str):
+        if not HAS_PEDALBOARD:
+            raise RuntimeError("pedalboard not available")
+        if not os.path.exists(self.vst_path):
+            raise FileNotFoundError(f"DecentSampler VST3 not found at {self.vst_path}")
+        if not os.path.exists(dspreset_path):
+            raise FileNotFoundError(f"Preset file not found at {dspreset_path}")
+
+        plugin = VST3Plugin(self.vst_path)
+
+        abs_preset = os.path.abspath(dspreset_path)
+        preset_dir = os.path.dirname(abs_preset)
+        cwd_before = os.getcwd()
+        try:
+            os.chdir(preset_dir)
+            plugin.load_preset(abs_preset)
+        finally:
+            os.chdir(cwd_before)
+
+        return plugin

app/main.py

@@ -1,4 +1,4 @@
-import os
+import os, threading
 from fastapi import FastAPI
 from fastapi.responses import HTMLResponse
 from fastapi.staticfiles import StaticFiles
@@ -14,6 +14,7 @@ from app.api.v1.user_config import router as user_config_router
 from app.api.v1.ai_proxy import router as ai_proxy_router
 from app.api.v1.plugins import router as plugins_router
 from app.core.auth import seed_admin
+from app.core.soundfont_converter import SoundFontConverter
 
 # Ensure storage directories exist
 os.makedirs(settings.UPLOADS_DIR, exist_ok=True)
@@ -55,6 +56,15 @@ app.include_router(plugins_router, prefix="/api/v1/plugins", tags=["plugins"])
 async def startup_seed_admin():
     seed_admin()
 
+@app.on_event("startup")
+async def startup_convert_soundfonts():
+    def _run():
+        try:
+            SoundFontConverter().batch_convert_all()
+        except Exception as e:
+            print(f"[Startup] SoundFont conversion error: {e}")
+    threading.Thread(target=_run, daemon=True).start()
+
 @app.get("/", response_class=HTMLResponse)
 async def get_index():
     index_path = os.path.join(settings.TEMPLATES_DIR, "index.html")

app/static/js/app.jsx

@@ -41,6 +41,9 @@ function getAudioContext() {
   if (audioCtx.state === 'suspended') {
     audioCtx.resume();
   }
+  if (window.SonicSF && window.SonicSF.init) {
+    window.SonicSF.init(audioCtx);
+  }
   return audioCtx;
 }
 const formatTime = secs => {
@@ -454,13 +457,15 @@ const WaveformLane = ({
     const PADDING_LEFT = 0;
     const tStart = (scrollLeftVal - leadIn * zoom) / zoom - PADDING_LEFT;
     const tEnd = (scrollLeftVal + drawWidth - leadIn * zoom) / zoom + CLIP_BUFFER / zoom;
-    const firstBeat = Math.floor(tStart / beatDuration) * beatDuration;
+    const firstBeatNum = Math.floor(tStart / beatDuration);
+    const lastBeatNum = Math.ceil(tEnd / beatDuration);
     let snapDivisor = 1;
     if (snapValue && snapValue !== 'free') {
       if (snapValue === '4') snapDivisor = 4; else if (snapValue === '1') snapDivisor = 1; else if (snapValue === '1/2') snapDivisor = 0.5; else if (snapValue === '1/4') snapDivisor = 0.25; else if (snapValue === '1/8') snapDivisor = 0.125; else if (snapValue === '1/16') snapDivisor = 0.0625; else if (snapValue === '1/32') snapDivisor = 0.03125;
     }
-    for (let t = firstBeat; t <= tEnd; t += beatDuration) {
-      const beatNum = Math.floor(t / beatDuration) + 1;
+    for (let bn = firstBeatNum; bn <= lastBeatNum; bn++) {
+      const t = bn * beatDuration;
+      const beatNum = bn + 1;
       const isBar = beatNum % 4 === 1;
       const localX = (t - tStart) * zoom;
       if (localX < -CLIP_BUFFER || localX > drawWidth + CLIP_BUFFER) continue;
@@ -1219,14 +1224,6 @@ const TimelineRuler = ({
     const ctx = canvas.getContext('2d');
     const dpr = window.devicePixelRatio || 1;
     let scrollLeftVal = scrollLeft || 0;
-    let el = canvas.parentElement;
-    while (el) {
-      if (el.scrollLeft !== undefined && (el.scrollWidth > el.clientWidth || el.scrollLeft > 0)) {
-        scrollLeftVal = el.scrollLeft;
-        break;
-      }
-      el = el.parentElement;
-    }
     const height = RULER_HEIGHT;
     canvas.width = Math.min(Math.round(drawWidth * dpr), 32768);
     canvas.height = Math.min(Math.round(height * dpr), 32768);
@@ -1248,6 +1245,27 @@ const TimelineRuler = ({
     const tStart = scrollLeftVal / zoom - PADDING_LEFT;
     const tEnd = (scrollLeftVal + drawWidth) / zoom + CLIP_BUFFER / zoom;
 
+    // Draw bar markers (aligned with TempoTrackLane)
+    const beatDuration = 60 / bpm;
+    const barDuration = beatDuration * 4;
+    const firstBarNum = Math.floor(tStart / barDuration);
+    const lastBarNum = Math.ceil(tEnd / barDuration);
+    for (let bn = firstBarNum; bn <= lastBarNum; bn++) {
+      const t = bn * barDuration;
+      const localX = (t - tStart) * zoom;
+      if (localX < -CLIP_BUFFER || localX > drawWidth + CLIP_BUFFER) continue;
+      ctx.strokeStyle = 'rgba(255, 255, 255, 0.25)';
+      ctx.lineWidth = 1.2;
+      ctx.beginPath();
+      ctx.moveTo(localX, 0);
+      ctx.lineTo(localX, height);
+      ctx.stroke();
+      ctx.fillStyle = 'rgba(255, 255, 255, 0.8)';
+      ctx.font = 'bold 10px Inter, sans-serif';
+      ctx.textAlign = 'center';
+      ctx.fillText(`${bn}`, localX, 32);
+    }
+
     // Draw time duration labels with drag-selection markers
     const minTimePx = 60;
     const rawSecInt = Math.max(1, Math.ceil(minTimePx / zoom));
@@ -1312,16 +1330,8 @@ const TempoTrackLane = ({
     if (!canvas) return;
     const ctx = canvas.getContext('2d');
     const dpr = window.devicePixelRatio || 1;
-    // Read scrollLeft from the DOM wrapper directly to stay in sync with tracks
+    // Use scrollLeft prop directly (DOM traversal broken by sticky wrapper)
     let scrollLeftVal = scrollLeft || 0;
-    let el = canvas.parentElement;
-    while (el) {
-      if (el.scrollLeft !== undefined && (el.scrollWidth > el.clientWidth || el.scrollLeft > 0)) {
-        scrollLeftVal = el.scrollLeft;
-        break;
-      }
-      el = el.parentElement;
-    }
     const height = 40;
     canvas.width = Math.min(Math.round(drawWidth * dpr), 32768);
     canvas.height = Math.min(Math.round(height * dpr), 32768);
@@ -1338,9 +1348,11 @@ const TempoTrackLane = ({
     const PADDING_LEFT = 0;
     const tStart = (scrollLeftVal - leadIn * zoom) / zoom - PADDING_LEFT;
     const tEnd = (scrollLeftVal + drawWidth - leadIn * zoom) / zoom + CLIP_BUFFER / zoom;
-    const firstBeat = Math.floor(tStart / beatDuration) * beatDuration;
-    for (let t = firstBeat; t <= tEnd; t += beatDuration) {
-      const beatNum = Math.floor(t / beatDuration) + 1;
+    const firstBeatNum = Math.floor(tStart / beatDuration);
+    const lastBeatNum = Math.ceil(tEnd / beatDuration);
+    for (let bn = firstBeatNum; bn <= lastBeatNum; bn++) {
+      const t = bn * beatDuration;
+      const beatNum = bn + 1;
       const isBar = beatNum % 4 === 1;
       const localX = (t - tStart) * zoom;
       if (localX < -CLIP_BUFFER || localX > drawWidth + CLIP_BUFFER) continue;
@@ -1378,8 +1390,10 @@ const TempoTrackLane = ({
       if (snapValue === '4') divisor = 4; else if (snapValue === '1') divisor = 1; else if (snapValue === '1/2') divisor = 0.5; else if (snapValue === '1/4') divisor = 0.25; else if (snapValue === '1/8') divisor = 0.125; else if (snapValue === '1/16') divisor = 0.0625; else if (snapValue === '1/32') divisor = 0.03125;
       const snapInterval = beatDuration * divisor;
       if (snapInterval * zoom >= 4) {
-        const firstSnap = Math.floor(tStart / snapInterval) * snapInterval;
-        for (let t = firstSnap; t <= tEnd; t += snapInterval) {
+        const firstSnapNum = Math.floor(tStart / snapInterval);
+        const lastSnapNum = Math.ceil(tEnd / snapInterval);
+        for (let sn = firstSnapNum; sn <= lastSnapNum; sn++) {
+          const t = sn * snapInterval;
           const onBeat = Math.abs(t / beatDuration - Math.round(t / beatDuration)) < 0.001;
           if (!onBeat) {
             const localX = (t - tStart) * zoom;
@@ -3351,9 +3365,13 @@ const PluginManagerModal = ({ isOpen, onClose, pluginsData }) => {
     try {
       const result = await window.SonicAPI.uploadSoundFont(file);
       setSfUploadStatus('Uploaded: ' + result.name);
-      // Refresh plugin list
+      // Refresh plugin list and catalog
       const data = await window.SonicAPI.listPlugins();
       setLocalData(data);
+      try {
+        const cat = await window.SonicAPI.getSoundfontCatalog();
+        window.__soundfontCatalog = cat;
+      } catch (_) {}
     } catch (err) {
       setSfUploadStatus('Error: ' + err.message);
     }
@@ -3448,9 +3466,9 @@ const PluginManagerModal = ({ isOpen, onClose, pluginsData }) => {
                       className: 'text-[10px] text-zinc-500 hover:text-red-400 opacity-0 group-hover:opacity-100 transition px-2 py-1'
                     }, 'Delete')
                   )
-                )
               )
-            ),
+            ))
+          ),
           // Upload section (bottom of right panel)
           React.createElement('div', {
             className: 'pt-4 mt-4 border-t border-[#383838]'
@@ -3553,9 +3571,8 @@ const PluginManagerModal = ({ isOpen, onClose, pluginsData }) => {
         )
       )
     )
-  ));
+  );
 };
-
 const ProfileModal = ({
   isOpen,
   onClose,
@@ -6126,6 +6143,11 @@ const serializeTracksList = (tracksList, secondsPerBar) => {
       instrument_id: t.instrumentId || null,
       instrument_program: t.instrumentProgram !== undefined ? t.instrumentProgram : null,
       instrument_name: t.instrumentName || null,
+      instrument_source: t.instrument_source || (t.synth_engine ? t.synth_engine.type : null),
+      soundfont_id: t.soundfont_id || (t.synth_engine ? t.synth_engine.soundfont_id : null),
+      soundfont_bank: t.soundfont_bank !== undefined ? t.soundfont_bank : (t.synth_engine ? t.synth_engine.soundfont_bank : null),
+      soundfont_program: t.soundfont_program !== undefined ? t.soundfont_program : (t.synth_engine ? t.synth_engine.soundfont_program : null),
+      synth_engine: t.synth_engine || undefined,
       items: items
     };
   });
@@ -6153,6 +6175,7 @@ const deserializeTracksList = (schemaTracks, secondsPerBar, sectionStore) => {
           name: item.name,
           startTime: item.start_bar * secondsPerBar,
           duration: item.duration_bars * secondsPerBar,
+          length_bars: item.duration_bars || 4,
           notes: (src.notes || []).map(n => ({
             id: n.id,
             pitch: n.pitch || 60,
@@ -6171,6 +6194,7 @@ const deserializeTracksList = (schemaTracks, secondsPerBar, sectionStore) => {
           name: item.name,
           start: item.start_bar * secondsPerBar,
           duration: item.duration_bars * secondsPerBar,
+          length_bars: item.duration_bars || 4,
           sectionId: secId,
           tracks: secContainer ? deserializeTracksList(secContainer.tracks, secondsPerBar, sectionStore) : null
         });
@@ -6192,7 +6216,12 @@ const deserializeTracksList = (schemaTracks, secondsPerBar, sectionStore) => {
       midiItems: midiItems,
       instrumentId: t.instrument_id || null,
       instrumentProgram: t.instrument_program !== null ? t.instrument_program : undefined,
-      instrumentName: t.instrument_name || null
+      instrumentName: t.instrument_name || null,
+      instrument_source: t.instrument_source || null,
+      soundfont_id: t.soundfont_id || null,
+      soundfont_bank: t.soundfont_bank !== null ? t.soundfont_bank : undefined,
+      soundfont_program: t.soundfont_program !== null ? t.soundfont_program : undefined,
+      synth_engine: t.synth_engine || undefined
     };
   });
 };
@@ -6395,8 +6424,48 @@ const App = () => {
   }]);
   const [appWarningModal, setAppWarningModal] = useState(null);
   const [bpm, setBpm] = useState(localStorage.getItem('studio_bpm') || '120');
-  const [draggedClip, setDraggedClip] = useState(null); // { trackId, clickOffset, buffer, name, volume, color }
+  const prevBpmRef = useRef(bpm);
+  const [draggedClip, setDraggedClip] = useState(null);
   const [hoveredTrackId, setHoveredTrackId] = useState(null);
+  // Recalculate item/section/selection durations when BPM changes
+  useEffect(() => {
+    const oldSpb = prevBpmRef.current ? (60.0 / parseFloat(prevBpmRef.current)) * 4 : null;
+    const bpmVal = parseFloat(bpm) || 120;
+    const secondsPerBar = (60.0 / bpmVal) * 4;
+    // Recalculate range loop selection to maintain bar count (tempo mode only)
+    if (oldSpb && selectionFollowsTempo && selectionStart !== null && selectionEnd !== null && selectionEnd > selectionStart) {
+      const startBar = selectionStart / oldSpb;
+      const endBar = selectionEnd / oldSpb;
+      if (endBar - startBar > 0.01) {
+        setSelectionStart(startBar * secondsPerBar);
+        setSelectionEnd(endBar * secondsPerBar);
+      }
+    }
+    prevBpmRef.current = bpm;
+    // Force canvas redraw
+    setCanvasRedrawCount(n => n + 1);
+    // Recalculate item/section durations
+    updateActiveTracks(prev => prev.map(t => ({
+      ...t,
+      midiItems: (t.midiItems || []).map(m => {
+        if (m.length_bars) return { ...m, duration: m.length_bars * secondsPerBar };
+        if (m.duration) {
+          // Legacy item without length_bars: compute bars from current duration/BPM
+          const bars = Math.max(0.25, Math.round(m.duration / secondsPerBar * 4) / 4);
+          return { ...m, length_bars: bars, duration: bars * secondsPerBar };
+        }
+        return m;
+      }),
+      sections: (t.sections || []).map(s => {
+        if (s.length_bars) return { ...s, duration: s.length_bars * secondsPerBar };
+        if (s.duration) {
+          const bars = Math.max(0.25, Math.round(s.duration / secondsPerBar * 4) / 4);
+          return { ...s, length_bars: bars, duration: bars * secondsPerBar };
+        }
+        return s;
+      })
+    })));
+  }, [bpm]);
   const openPanel = id => {
     if (id === 'export') setShowExportPanel(true); else if (id === 'ai') setShowAIPanel(true); else if (id === 'python_tools') setShowPythonToolsPanel(true); else if (id === 'selection') setShowSelectionPanel(true);
   };
@@ -6410,27 +6479,48 @@ const App = () => {
   const [instrumentSelectorData, setInstrumentSelectorData] = useState(null);
   const openInstrumentSelector = trackId => {
     setInstrumentSelectorTrackId(trackId);
-    const track = activeTracks.find(t => t.id === trackId);
-    if (track && track.instrumentId && track.instrumentId.startsWith('sf_')) {
-      // Track already has a SoundFont assigned → open instrument selection directly
-      setSynthCategory('soundfont');
-      setSelectedSoundFontId(track.instrumentId);
-      setSfPresets(null);
-      const sfIdParam = track.instrumentId.replace('sf_', '');
-      window.SonicAPI.listSoundfontInstruments(sfIdParam)
-        .then(data => setSfPresets(data.presets || []))
-        .catch(() => setSfPresets([]));
-    } else {
-      // Reset synth state and always reload plugin data
-      setSynthCategory(null);
-      setSelectedSoundFontId(null);
-      window.SonicAPI.listPlugins().then(data => setInstrumentSelectorData(data)).catch(e => console.error('listPlugins failed:', e));
+    setSfPresetSearchQuery('');
+    // Build flat instrument list from all soundfonts
+    const sfonts = instrumentSelectorData?.soundfonts || [];
+    const allInstruments = [];
+    (sfonts || []).forEach(sf => {
+      const sfId = sf.id.startsWith('sf_') ? sf.id : 'sf_' + sf.id;
+      const sfName = sf.display || sf.name || sf.id;
+      (sf.presets || []).forEach(p => {
+        allInstruments.push({
+          ...p,
+          _sfId: sfId,
+          _sfName: sfName,
+          _sfDisplay: sfName.substring(0, 30)
+        });
+      });
+    });
+    setSfPresets(allInstruments.length > 0 ? allInstruments : null);
+    // Fallback: if no cached presets, fetch on demand per soundfont
+    if (allInstruments.length === 0) {
+      Promise.all((sfonts || []).map(sf => {
+        const sfId = sf.id.replace('sf_', '');
+        return window.SonicAPI.listSoundfontInstruments(sfId)
+          .then(data => ({ sf, presets: data.presets || [] }))
+          .catch(() => ({ sf, presets: [] }));
+      })).then(results => {
+        const all = [];
+        results.forEach(({ sf, presets }) => {
+          const sfId = sf.id.startsWith('sf_') ? sf.id : 'sf_' + sf.id;
+          const sfName = sf.display || sf.name || sf.id;
+          presets.forEach(p => {
+            all.push({ ...p, _sfId: sfId, _sfName: sfName, _sfDisplay: sfName.substring(0, 30) });
+          });
+        });
+        setSfPresets(all);
+      });
     }
   };
   const closeInstrumentSelector = () => {
     setInstrumentSelectorTrackId(null);
     setSynthCategory(null);
     setSelectedSoundFontId(null);
+    setSfPresetSearchQuery('');
   };
   const [synthCategory, setSynthCategory] = useState(null); // 'vst' | 'soundfont'
   const [selectedSoundFontId, setSelectedSoundFontId] = useState(null);
@@ -6438,6 +6528,7 @@ const App = () => {
   const [instrumentDropdownTrackId, setInstrumentDropdownTrackId] = useState(null);
   const [instrumentDropdownBtnRect, setInstrumentDropdownBtnRect] = useState(null);
   const [instrumentSearchQuery, setInstrumentSearchQuery] = useState('');
+  const [sfPresetSearchQuery, setSfPresetSearchQuery] = useState('');
   const filteredInstruments = useMemo(() => {
     if (!instrumentSelectorData || !instrumentSearchQuery) return { soundfonts: instrumentSelectorData?.soundfonts || [], vst: instrumentSelectorData?.vst_instruments || [] };
     const q = instrumentSearchQuery.toLowerCase();
@@ -6448,7 +6539,24 @@ const App = () => {
   }, [instrumentSearchQuery, instrumentSelectorData]);
   useEffect(() => {
     if (!instrumentSelectorData) {
-      window.SonicAPI.listPlugins().then(data => setInstrumentSelectorData(data)).catch(() => {});
+      window.SonicAPI.listPlugins().then(async data => {
+        // Eagerly fetch full catalog with all instrument presets
+        try {
+          const catResp = await window.SonicAPI.getSoundfontCatalog?.() ?? await fetch('/api/v1/plugins/soundfonts/catalog').then(r => r.json());
+          const catalog = catResp.full_catalog || {};
+          // Merge presets into each soundfont entry
+          data.soundfonts = (data.soundfonts || []).map(sf => {
+            const sfId = sf.id.replace('sf_', '');
+            // Catalog keys are lowercased by soundfont_inspector
+            const catEntry = catalog[sfId.toLowerCase()] || catalog[sfId];
+            if (catEntry && catEntry.instruments) {
+              return { ...sf, presets: catEntry.instruments };
+            }
+            return sf;
+          });
+        } catch (e) { console.warn('Catalog fetch error:', e); }
+        setInstrumentSelectorData(data);
+      }).catch(() => {});
     }
   }, []);
   useEffect(() => {
@@ -6479,16 +6587,34 @@ const App = () => {
     "Tinkle Bell","Agogo","Steel Drums","Woodblock","Taiko Drum","Melodic Tom","Synth Drum","Reverse Cymbal",
     "Guitar Fret Noise","Breath Noise","Seashore","Bird Tweet","Telephone Ring","Helicopter","Applause","Gunshot"
   ];
-  const setTrackInstrumentWithProgram = (trackId, instrumentId, programNumber, displayName) => {
+  const setTrackInstrumentWithProgram = (trackId, instrumentId, programNumber, displayName, bankNumber) => {
+    const isSfInstrument = instrumentId && typeof instrumentId === 'string' && instrumentId.startsWith('sf_');
+    const sfBank = bankNumber !== undefined ? bankNumber : (isSfInstrument ? 0 : undefined);
+    const sfProg = programNumber !== undefined ? programNumber : undefined;
     updateActiveTracks(prev => prev.map(t => {
       if (t.id !== trackId) return t;
-      return { ...t, instrumentId, instrumentProgram: programNumber !== undefined ? programNumber : undefined, instrumentName: displayName };
+      const hasInstrument = !!instrumentId;
+      const instrType = isSfInstrument ? 'soundfont' : (hasInstrument ? 'vst3' : 'default');
+      const synthEngine = hasInstrument ? {
+        type: instrType,
+        plugin_id: instrumentId,
+        soundfont_bank: sfBank !== undefined ? sfBank : 0,
+        soundfont_program: sfProg !== undefined ? sfProg : 0,
+        soundfont_id: isSfInstrument ? instrumentId.replace('sf_', '') : ''
+      } : undefined;
+      return { ...t, instrumentId, instrumentProgram: sfProg, instrumentName: displayName, soundfont_bank: sfBank, soundfont_program: sfProg, synth_engine: synthEngine, type: hasInstrument ? 'MIDI' : (t.type === 'MIDI' ? 'audio' : t.type) };
     }));
     setInstrumentDropdownTrackId(null);
     setInstrumentDropdownBtnRect(null);
     setInstrumentSelectorTrackId(null);
     setSynthCategory(null);
     setSelectedSoundFontId(null);
+    // Trigger SpessaSynth load + program change when soundfont instrument selected
+    if (window.SonicSF && window.SonicSF.selectInstrument && instrumentId && isSfInstrument) {
+      const sfId = instrumentId.replace('sf_', '');
+      const ch = sfBank === 128 ? 9 : 0;
+      window.SonicSF.selectInstrument(ch, sfBank || 0, sfProg || 0, sfId);
+    }
     setSubTabs(prev => prev.map(s => {
       if (s.trackId !== trackId) return s;
       return { ...s, instrumentProgram: programNumber !== undefined ? programNumber : undefined, instrumentName: displayName, instrumentId };
@@ -6534,17 +6660,25 @@ const App = () => {
       // Set instrument on track immediately so Synth button shows the name
       updateActiveTracks(prev => prev.map(t => {
         if (t.id !== trackId) return t;
-        return { ...t, instrumentId, instrumentProgram: undefined, instrumentName: displayName };
+        const sfClean = instrumentId.replace('sf_', '');
+        const synthEngine = { type: 'soundfont', plugin_id: instrumentId, soundfont_bank: 0, soundfont_program: 0, soundfont_id: sfClean };
+        return { ...t, instrumentId, instrumentProgram: undefined, instrumentName: displayName, synth_engine: synthEngine };
       }));
       setSelectedSoundFontId(instrumentId);
       setSynthCategory('soundfont');
       setInstrumentSelectorTrackId(trackId);
       setSfPresets(null);
-      // Fetch actual presets from the SoundFont
+      setSfPresetSearchQuery('');
       const sfIdParam = instrumentId.replace('sf_', '');
-      window.SonicAPI.listSoundfontInstruments(sfIdParam)
-        .then(data => setSfPresets(data.presets || []))
-        .catch(e => { console.error('listSoundfontInstruments failed:', e); setSfPresets([]); });
+      // Use cached presets from instrumentSelectorData
+      const cachedSf = (instrumentSelectorData?.soundfonts || []).find(s => s.id === instrumentId || s.id === sfIdParam);
+      if (cachedSf && cachedSf.presets) {
+        setSfPresets(cachedSf.presets);
+      } else {
+        window.SonicAPI.listSoundfontInstruments(sfIdParam)
+          .then(data => setSfPresets(data.presets || []))
+          .catch(e => { console.error('listSoundfontInstruments failed:', e); setSfPresets([]); });
+      }
     } else {
       setTrackInstrumentWithProgram(trackId, instrumentId, undefined, displayName);
     }
@@ -6570,6 +6704,7 @@ const App = () => {
   const [isPlaying, setIsPlaying] = useState(false);
   const [selectionStart, setSelectionStart] = useState(null);
   const [selectionEnd, setSelectionEnd] = useState(null);
+  const [selectionFollowsTempo, setSelectionFollowsTempo] = useState(true);
   const selectionRef = useRef({ start: null, end: null });
   selectionRef.current = { start: selectionStart, end: selectionEnd };
   const [selectionMode, setSelectionMode] = useState(null); // 'global' (from ruler) | 'local' (from track)
@@ -6617,25 +6752,64 @@ const App = () => {
              const cmd = msg.data[0] >> 4;
              const pitch = msg.data[1];
              const velocity = msg.data[2];
-              if (cmd === 0x9 && velocity > 0) {
-                lastMidiNoteRef.current = { pitch, velocity, startTime: performance.now(), length: 0 };
-                setLastMidiNote({ pitch, velocity, length: 0, time: Date.now() });
-                activeMidiPitchesRef.current.add(pitch);
-                setActiveMidiPitches(new Set(activeMidiPitchesRef.current));
-                try {
-                  const ar = activeTabRef && subTabsRef && subTabsRef.current.find(s => s.id === activeTabRef.current && s.type === 'PIANO_ROLL' && s.isArmed);
-                  if (ar && window.SonicSF) {
-                    window.SonicSF.playNote(pitch, velocity, 500, undefined, ar.instrumentProgram, null);
-                  }
-                } catch (e) {}
-              } else if (cmd === 0x8 || (cmd === 0x9 && velocity === 0)) {
-                activeMidiPitchesRef.current.delete(pitch);
-                setActiveMidiPitches(new Set(activeMidiPitchesRef.current));
-                const current = lastMidiNoteRef.current;
-              if (current && current.pitch === pitch) {
-                const lenSec = (performance.now() - current.startTime) / 1000;
-                lastMidiNoteRef.current = { ...current, length: lenSec };
-                setLastMidiNote(prev => prev && prev.pitch === pitch ? { ...prev, length: lenSec, time: Date.now() } : prev);
+               if (cmd === 0x9 && velocity > 0) {
+                  lastMidiNoteRef.current = { pitch, velocity, startTime: performance.now(), length: 0 };
+                  setLastMidiNote({ pitch, velocity, length: 0, time: Date.now() });
+                  activeMidiPitchesRef.current.add(pitch);
+                  setActiveMidiPitches(new Set(activeMidiPitchesRef.current));
+                   // Stop previous notes on this channel before playing new note
+                   // Only send All Notes Off when sustain pedal is not active
+                   { if (window.SonicSF) {
+                     const ch = msg.data[0] & 0x0F;
+                     if (!window.SonicSF.sustainActive || !window.SonicSF.sustainActive(ch)) {
+                       try { window.SonicSF.controllerChange(ch, 123, 0); } catch (e) {}
+                     }
+                     const arSub = subTabsRef && subTabsRef.current && activeTabRef && subTabsRef.current.find(s => s.id === activeTabRef.current && s.type === 'PIANO_ROLL' && s.isArmed);
+                    if (arSub) {
+                      window.SonicSF.playNote(pitch, velocity, 60000, undefined, arSub.instrumentProgram, null, ch, arSub.synth_engine);
+                    } else {
+                      const armedTrack = activeTracksRef.current ? activeTracksRef.current.find(t => t.isArmed) : null;
+                      if (armedTrack) {
+                        const prog = armedTrack.instrumentProgram;
+                        const se = armedTrack.synth_engine;
+                        const dest = activeTrackNodesRef.current[armedTrack.id]?.gainNode || null;
+                        window.SonicSF.playNote(pitch, velocity, 60000, undefined, prog, dest, ch, se);
+                      }
+                    }
+                  } }
+               } else if (cmd === 0x8 || (cmd === 0x9 && velocity === 0)) {
+                 activeMidiPitchesRef.current.delete(pitch);
+                 setActiveMidiPitches(new Set(activeMidiPitchesRef.current));
+                 const current = lastMidiNoteRef.current;
+               if (current && current.pitch === pitch) {
+                 const lenSec = (performance.now() - current.startTime) / 1000;
+                 lastMidiNoteRef.current = { ...current, length: lenSec };
+                 setLastMidiNote(prev => prev && prev.pitch === pitch ? { ...prev, length: lenSec, time: Date.now() } : prev);
+               }
+               // Stop the note immediately via SpessaSynth
+               if (window.SonicSF && window.SonicSF.stopNote) {
+                 const ch = msg.data[0] & 0x0F;
+                 window.SonicSF.stopNote(ch, pitch);
+               }
+              }
+            }
+
+            // ── Sustain (CC64), Modulation (CC1), Pitch Bend ──
+            const midiCh = msg.data[0] & 0x0F;
+            if (cmd === 0xB) {
+              // Controller Change: forward all CCs to SpessaSynth
+              const cc = msg.data[1];
+              const val = msg.data[2];
+              if (window.SonicSF && window.SonicSF.controllerChange) {
+                window.SonicSF.controllerChange(midiCh, cc, val);
+              }
+            } else if (cmd === 0xE) {
+              // Pitch Bend: 14-bit value (LSB + MSB)
+              const lsb = msg.data[1];
+              const msb = msg.data[2];
+              const bendVal = (msb << 7) | lsb;
+              if (window.SonicSF && window.SonicSF.pitchBend) {
+                window.SonicSF.pitchBend(midiCh, bendVal);
               }
             }
 
@@ -7027,6 +7201,11 @@ const App = () => {
             if (active) setSelectedProviderId(active.id);
           }
         } catch (e) { }
+        try {
+          window.SonicAPI.getSoundfontCatalog().then(cat => {
+            window.__soundfontCatalog = cat;
+          }).catch(() => {});
+        } catch (e) { }
       })();
     }
   };
@@ -7212,6 +7391,8 @@ const App = () => {
   const rulerDragStartRef = useRef(null);
   const rulerAnchorRef = useRef(null);
   const isDraggingRulerRef = useRef(false);
+  const subTabDragStartRef = useRef(null);
+  const isDraggingSubTabRef = useRef(false);
   const handlePlayPauseRef = useRef(null);
   const currentTimeRef = useRef(currentTime);
   currentTimeRef.current = currentTime;
@@ -10038,6 +10219,7 @@ const App = () => {
     const track = activeTracksRef.current ? activeTracksRef.current.find(t => t.id === st.trackId) : null;
     const destNode = getOrCreateTrackNode(track, context);
     const instrumentProgram = track ? track.instrumentProgram : undefined;
+    const synthEngine = track ? track.synth_engine : undefined;
     midiNotes.forEach(note => {
       const noteOnBeat = note.start_beat || 0;
       const noteDurBeat = note.duration_beats || 1;
@@ -10049,7 +10231,7 @@ const App = () => {
         const scheduledTime = startWallTime + effectiveStart;
         const durMs = effectiveDur * 1000;
         if (window.SonicSF) {
-          window.SonicSF.playNote(note.pitch || 60, note.velocity || 0.8, durMs, scheduledTime, instrumentProgram, destNode);
+          window.SonicSF.playNote(note.pitch || 60, note.velocity || 0.8, durMs, scheduledTime, instrumentProgram, destNode, undefined, synthEngine);
         }
       }
     });
@@ -10533,31 +10715,33 @@ const App = () => {
             };
             return { ...t, midiItems: updatedItems };
           }
-          const newMidiItem = {
+        const newMidiItem = {
             id: 'midi_rec_' + Date.now(),
             name: 'Recorded MIDI',
             startTime: recordingStartTimeRef.current,
             duration: Math.ceil(totalDurationBeats / 4) * secondsPerBar,
+            length_bars: Math.ceil(totalDurationBeats / 4),
             notes: recordedNotes
-          };
-          return {
+        };
+        return {
             ...t,
             midiItems: [...(t.midiItems || []), newMidiItem]
-          };
+        };
         }));
 
         if (recordedNotes.length > 0) {
-          hasRecordedAnything = true;
+        hasRecordedAnything = true;
         }
-      } else if (recordedNotes.length > 0) {
+    } else if (recordedNotes.length > 0) {
         hasRecordedAnything = true;
         const totalDurationBeats = Math.max(4.0, ...recordedNotes.map(n => n.start_beat + n.duration_beats));
         const newMidiItem = {
-          id: 'midi_rec_' + Date.now(),
-          name: 'Recorded MIDI',
-          startTime: recordingStartTimeRef.current,
-          duration: Math.ceil(totalDurationBeats / 4) * secondsPerBar,
-          notes: recordedNotes
+            id: 'midi_rec_' + Date.now(),
+            name: 'Recorded MIDI',
+            startTime: recordingStartTimeRef.current,
+            duration: Math.ceil(totalDurationBeats / 4) * secondsPerBar,
+            length_bars: Math.ceil(totalDurationBeats / 4),
+            notes: recordedNotes
         };
         updateActiveTracks(prev => prev.map(t => {
           if (t.id !== trackId) return t;
@@ -10688,8 +10872,6 @@ const App = () => {
       setSelectionEnd(selE);
     } else {
       rulerAnchorRef.current = Math.max(0, time);
-      setSelectionStart(Math.max(0, time));
-      setSelectionEnd(Math.max(0, time));
     }
     handlePlayheadSet(time);
   };
@@ -10717,9 +10899,28 @@ const App = () => {
     };
     document.addEventListener('mousemove', handleMouseMove);
     document.addEventListener('mouseup', handleMouseUp);
+    // Sub-tab ruler drag (section/editor tabs)
+    const handleSubTabMove = e => {
+      if (!isDraggingSubTabRef.current) return;
+      const wrapper = timelineWrapperRef.current;
+      if (!wrapper) return;
+      const rect = wrapper.getBoundingClientRect();
+      const sl = wrapper.scrollLeft;
+      const raw = Math.max(0, (e.clientX - rect.left + sl) / zoom);
+      const time = snapValueRef.current !== 'free' ? snapTime(raw, snapValueRef.current, bpmRef.current) : raw;
+      const anchor = subTabDragStartRef.current ?? 0;
+      setSubTabs(prev => prev.map(s => s.id === activeTabRef.current ? { ...s, selectionStart: Math.min(anchor, time), selectionEnd: Math.max(anchor, time) } : s));
+    };
+    const handleSubTabUp = () => {
+      if (isDraggingSubTabRef.current) { isDraggingSubTabRef.current = false; subTabDragStartRef.current = null; }
+    };
+    document.addEventListener('mousemove', handleSubTabMove);
+    document.addEventListener('mouseup', handleSubTabUp);
     return () => {
       document.removeEventListener('mousemove', handleMouseMove);
       document.removeEventListener('mouseup', handleMouseUp);
+      document.removeEventListener('mousemove', handleSubTabMove);
+      document.removeEventListener('mouseup', handleSubTabUp);
     };
   }, [zoom, maxDuration]);
 
@@ -11426,6 +11627,18 @@ const App = () => {
     });
     setTimeout(() => lucide.createIcons(), 50);
   };
+  const toggleTrackDrum = trackId => {
+    setTracks(prev => prev.map(t => t.id === trackId ? {
+      ...t,
+      is_percussion: !t.is_percussion,
+      soundfont_bank: !t.is_percussion ? 128 : (t._saved_sf_bank !== undefined ? t._saved_sf_bank : 0),
+      synth_engine: t.synth_engine ? {
+        ...t.synth_engine,
+        soundfont_bank: !t.is_percussion ? 128 : 0
+      } : t.synth_engine
+    } : t));
+    setTimeout(() => lucide.createIcons(), 50);
+  };
   const updateTrackVolumeDb = (trackId, val) => {
     const beforeSnap = captureTrackSnapshot(trackId);
     setTracks(prev => prev.map(t => t.id === trackId ? {
@@ -11792,11 +12005,13 @@ const App = () => {
     const curTracks = activeTracks;
     const track = curTracks.find(t => t.id === selectedTrackId);
     if (!track) { showToast('Chọn track trước', 'warning'); return; }
+    const secondsPerBar = (60.0 / (parseInt(bpm) || 120)) * 4;
     const section = {
       id: `sec_${Date.now()}`,
       name: 'Section',
       start: currentTime,
-      duration: 4,
+      duration: 4 * secondsPerBar,
+      length_bars: 4,
       color: track.color || '#06b6d4'
     };
     updateActiveTracks(prev => prev.map(t => t.id === selectedTrackId ? {
@@ -11817,6 +12032,7 @@ const App = () => {
       name: 'MIDI Item',
       startTime: currentTime,
       duration: 4 * secondsPerBar,
+      length_bars: 4,
       notes: [],
       color: '#a78bfa'
     };
@@ -13786,12 +14002,14 @@ const App = () => {
               };
               updatedTracks.push(targetTrack);
             }
+            // Place MIDI item at current playhead position
             const itemStartTimeSec = currentTime;
             const newMidiItem = {
               id: 'item_ai_' + Date.now() + '_' + Math.random().toString(36).substr(2, 5),
               name: `${composition_title || 'AI Theme'} - ${aiTrack.track_name}`,
               startTime: itemStartTimeSec,
               duration: durationSec,
+              length_bars: total_bars,
               notes: aiTrack.notes.map((note, index) => ({
                 id: `note_ai_${Date.now()}_${index}`,
                 pitch: note.pitch,
@@ -13802,6 +14020,22 @@ const App = () => {
               }))
             };
             targetTrack.midiItems = [...(targetTrack.midiItems || []), newMidiItem];
+            if (aiTrack.soundfont_bank !== undefined && aiTrack.soundfont_program !== undefined) {
+              targetTrack.soundfont_bank = aiTrack.soundfont_bank;
+              targetTrack.soundfont_program = aiTrack.soundfont_program;
+              targetTrack.soundfont_id = aiTrack.soundfont_id || '';
+              const sfEngine = {
+                type: 'soundfont',
+                plugin_id: aiTrack.soundfont_id ? 'sf_' + aiTrack.soundfont_id : null,
+                soundfont_bank: aiTrack.soundfont_bank,
+                soundfont_program: aiTrack.soundfont_program,
+                soundfont_id: aiTrack.soundfont_id || ''
+              };
+              targetTrack.synth_engine = sfEngine;
+              if (window.SonicSF && window.SonicSF.applyAITrackInstrument) {
+                window.SonicSF.applyAITrackInstrument(aiTrack.soundfont_bank, aiTrack.soundfont_program, sfEngine);
+              }
+            }
           });
           return updatedTracks;
         });
@@ -14631,7 +14865,56 @@ const App = () => {
   }))), /*#__PURE__*/React.createElement("div", {
     className: "w-[1px] h-5 bg-zinc-800 mx-0.5"
   }), /*#__PURE__*/React.createElement("button", {
-    onClick: () => setIsLoopingSelection(prev => !prev),
+        onClick: () => {
+          setIsLoopingSelection(prev => !prev);
+          // Sync loop state with active sub-tab (piano roll / audio editor)
+          const activeSub = activeTab && subTabs.find(s => s.id === activeTab && ['PIANO_ROLL', 'AUDIO_CLIP_EDITOR', 'SECTION_EDITOR'].includes(s.type));
+          if (activeSub) {
+            const newLoop = !activeSub.isLooping;
+            setSubTabs(prev => prev.map(s => s.id === activeTab ? { ...s, isLooping: newLoop } : s));
+            if (newLoop) {
+              const bpmVal = parseInt(bpm) || 120;
+              const beatSec = 60.0 / bpmVal;
+              let maxEnd = 0;
+              if (activeSub.type === 'PIANO_ROLL') {
+                (activeSub.notes || []).forEach(n => {
+                  const end = (n.start_beat || 0) + (n.duration_beats || 1);
+                  if (end > maxEnd) maxEnd = end;
+                });
+              } else if (activeSub.type === 'SECTION_EDITOR') {
+                (activeSub.clips || []).forEach(c => {
+                  const end = (c.startTime || 0) + (c.duration || 0);
+                  if (end > maxEnd) maxEnd = end;
+                });
+              } else if (activeSub.type === 'AUDIO_CLIP_EDITOR') {
+                const dur = activeSub.buffer?.duration || 0;
+                if (dur > maxEnd) maxEnd = dur;
+              }
+              const loopEndTime = activeSub.type === 'PIANO_ROLL' ? Math.max(maxEnd, 16) * beatSec + 1.0 : Math.max(maxEnd, 1);
+              setSubTabs(prev => prev.map(s => s.id === activeTab ? { ...s, selectionStart: 0, selectionEnd: loopEndTime } : s));
+            }
+          } else {
+            // Main timeline: auto-derive loop end from tracks
+            const bpmVal = parseInt(bpm) || 120;
+            const secPerBar = (60.0 / bpmVal) * 4;
+            let maxEnd = 0;
+            activeTracks.forEach(t => {
+              (t.clips || []).forEach(c => {
+                const end = (c.startTime || 0) + (c.duration || 0);
+                if (end > maxEnd) maxEnd = end;
+              });
+              (t.items || []).forEach(it => {
+                const end = (it.start || 0) + (it.duration || 4);
+                if (end > maxEnd) maxEnd = end;
+              });
+            });
+            if (maxEnd > 0) {
+              const loopEnd = maxEnd + secPerBar * 2;
+              setSelectionStart(0);
+              setSelectionEnd(loopEnd);
+            }
+          }
+        },
     className: `w-7 h-7 flex items-center justify-center rounded border transition ${isLoopingSelection ? 'bg-amber-600 text-black border-amber-500 hover:bg-amber-500' : 'bg-zinc-800 text-zinc-200 border-zinc-700 hover:bg-zinc-700'}`,
     title: isLoopingSelection ? (selLeft !== null && selRight !== null ? "Loop vùng chọn" : "Loop timeline") : "Bật loop"
   }, /*#__PURE__*/React.createElement("span", {
@@ -14703,7 +14986,11 @@ const App = () => {
     value: numberBar,
     readOnly: true,
     className: "w-14 bg-black text-zinc-400 text-[14px] px-1 py-0.5 rounded border border-zinc-800 text-center font-mono"
-  }), /*#__PURE__*/React.createElement("div", {
+  }), /*#__PURE__*/React.createElement("button", {
+    onClick: () => setSelectionFollowsTempo(prev => !prev),
+    className: `px-1.5 py-0.5 text-[14px] rounded border font-bold ${selectionFollowsTempo ? 'bg-amber-700 text-white border-amber-500' : 'bg-zinc-800 text-zinc-400 border-zinc-700'}`,
+    title: selectionFollowsTempo ? "Selection theo tempo (đổi BPM → selection thay đổi)" : "Selection theo thời gian (cố định)"
+  }, selectionFollowsTempo ? "♪T" : "⏱T"), /*#__PURE__*/React.createElement("div", {
     className: "w-[1px] h-6 bg-zinc-800 mx-1.5"
   }), /*#__PURE__*/React.createElement("span", {
     className: "text-[14px] text-zinc-500"
@@ -15494,6 +15781,13 @@ const App = () => {
         title: "Solo",
         className: `px-1.5 py-0.5 text-[10px] rounded font-mono font-bold border transition flex items-center gap-0.5 ${soloedTrackId === track.id || track.solo ? 'bg-amber-950 text-amber-400 border-amber-600' : 'bg-zinc-800 text-zinc-400 border-transparent hover:text-zinc-200'}`
       }, /*#__PURE__*/React.createElement("i", { "data-lucide": soloedTrackId === track.id || track.solo ? "headphones" : "headphone-off", className: "w-3 h-3" })), /*#__PURE__*/React.createElement("button", {
+        onClick: e => {
+          e.stopPropagation();
+          toggleTrackDrum(track.id);
+        },
+        title: track.is_percussion ? "Drum Channel (CH 10) - Click to disable" : "Toggle Drum Channel (CH 10)",
+        className: `px-1.5 py-0.5 text-[9px] rounded font-mono font-bold border transition flex items-center gap-0.5 ${track.is_percussion ? 'bg-rose-900 text-rose-300 border-rose-700' : 'bg-zinc-800 text-zinc-500 border-transparent hover:text-zinc-300'}`
+      }, /*#__PURE__*/React.createElement("span", { className: "text-[11px]" }, "🥁"), track.is_percussion ? /*#__PURE__*/React.createElement("span", { className: "text-[9px]" }, "D") : null), /*#__PURE__*/React.createElement("button", {
         onClick: e => {
           e.stopPropagation();
           toggleTrackArm(track.id);
@@ -15501,10 +15795,6 @@ const App = () => {
         title: "ARM (Record)",
         className: `px-1.5 py-0.5 text-[10px] rounded font-mono font-bold border transition flex items-center gap-0.5 ${track.isArmed ? 'bg-red-600 text-white border-red-500 hover:bg-red-500' : 'bg-zinc-800 text-zinc-400 border-transparent hover:text-zinc-200'}`
       }, /*#__PURE__*/React.createElement("i", { "data-lucide": "circle", className: `w-2.5 h-2.5 ${track.isArmed ? 'fill-white' : ''}` })), /*#__PURE__*/React.createElement("button", {
-        onClick: e => { e.stopPropagation(); const btn = e.currentTarget; setInstrumentDropdownTrackId(prev => prev === track.id ? null : track.id); setInstrumentDropdownBtnRect(btn.getBoundingClientRect()); setInstrumentSearchQuery(''); },
-        title: track.instrumentName || track.instrumentId || "Synth",
-        className: `px-1.5 py-0.5 text-[10px] rounded font-mono font-bold border transition flex items-center gap-0.5 max-w-[60px] ${track.instrumentId ? 'bg-violet-900 text-violet-300 border-violet-700' : 'bg-zinc-800 text-zinc-500 border-transparent hover:text-zinc-300'}`
-      }, /*#__PURE__*/React.createElement("i", { "data-lucide": "music", className: "w-3 h-3 shrink-0" }), /*#__PURE__*/React.createElement("span", { className: "truncate text-[9px]" }, track.instrumentName || track.instrumentId || (instrumentDropdownTrackId === track.id ? '' : 'Synth')), /*#__PURE__*/React.createElement("i", { "data-lucide": "chevron-down", className: "w-2.5 h-2.5 shrink-0" })), /*#__PURE__*/React.createElement("button", {
         onClick: e => {
           e.stopPropagation();
           toggleTrackMonitor(track.id);
@@ -15629,7 +15919,7 @@ const App = () => {
       })), " FX: ", /*#__PURE__*/React.createElement("span", {
         className: "text-zinc-500 font-normal"
       }, track.fxType || "None")), /*#__PURE__*/React.createElement("button", {
-        onClick: (e) => { e.stopPropagation(); const btn = e.currentTarget; setInstrumentDropdownTrackId(prev => prev === track.id ? null : track.id); setInstrumentDropdownBtnRect(btn.getBoundingClientRect()); setInstrumentSearchQuery(''); },
+        onClick: (e) => { e.stopPropagation(); openInstrumentSelector(track.id); },
         className: "px-2.5 py-1 bg-zinc-800 hover:bg-zinc-700 text-amber-400 border border-amber-800 rounded text-xs font-bold flex items-center gap-1 max-w-[120px]"
       }, /*#__PURE__*/React.createElement("span", {
         className: "inline-flex items-center shrink-0"
@@ -15655,6 +15945,8 @@ const App = () => {
         width: `${timelineWidth}px`
       },
       className: "relative flex flex-col min-h-full"
+    }, /*#__PURE__*/React.createElement("div", {
+      className: "sticky top-0 z-30 bg-[#1a1a1a]"
     }, /*#__PURE__*/React.createElement(TimelineRuler, {
       bpm: parseInt(bpm) || 120,
       zoom: zoom,
@@ -15662,7 +15954,7 @@ const App = () => {
       viewportWidth: viewportWidth,
       onPlayheadSet: handlePlayheadSet,
       snapValue: snapValue,
-      onRulerMouseDown: handleRulerMouseDown,
+      onRulerMouseDown: e => { setSelectionFollowsTempo(false); handleRulerMouseDown(e); },
       scrollLeft: scrollLeft,
       canvasRedrawCount: canvasRedrawCount
     }), /*#__PURE__*/React.createElement(TempoTrackLane, {
@@ -15672,10 +15964,10 @@ const App = () => {
       viewportWidth: viewportWidth,
       onPlayheadSet: handlePlayheadSet,
       snapValue: snapValue,
-      onRulerMouseDown: handleRulerMouseDown,
+      onRulerMouseDown: e => { setSelectionFollowsTempo(true); handleRulerMouseDown(e); },
       scrollLeft: scrollLeft,
       canvasRedrawCount: canvasRedrawCount
-    }), selectionMode === 'global' && selLeft !== null && selRight !== null && selRight > selLeft && /*#__PURE__*/React.createElement("div", {
+    })), selectionMode === 'global' && selLeft !== null && selRight !== null && selRight > selLeft && /*#__PURE__*/React.createElement("div", {
       className: "absolute inset-0 pointer-events-none z-20",
       style: {
         left: `${selLeft * zoom}px`,
@@ -16225,6 +16517,8 @@ const App = () => {
           width: `${subTabTimelineWidth}px`
         },
         className: "relative flex flex-col min-h-full"
+      }, /*#__PURE__*/React.createElement("div", {
+        className: "sticky top-0 z-30 bg-[#1a1a1a]"
       }, /*#__PURE__*/React.createElement(TimelineRuler, {
         bpm: parseInt(bpm) || 120,
         zoom: zoom,
@@ -16233,18 +16527,27 @@ const App = () => {
         onPlayheadSet: setCurrentTime,
         snapValue: snapValue,
         onRulerMouseDown: e => {
+          setSelectionFollowsTempo(false);
           const wrapper = timelineWrapperRef.current;
           if (!wrapper) return;
           const rect = wrapper.getBoundingClientRect();
           const sl = wrapper.scrollLeft;
           const raw = Math.max(0, (e.clientX - rect.left + sl) / zoom);
           const t = snapValue !== 'free' ? snapTime(raw, snapValue, bpm) : raw;
+          if (e.ctrlKey) {
+            e.preventDefault();
+            e.stopPropagation();
+            setSubTabs(prev => prev.map(s => s.id === activeTab ? { ...s, selectionStart: null, selectionEnd: null } : s));
+            return;
+          }
           if (e.shiftKey) { e.preventDefault(); e.stopPropagation(); }
           handlePlayheadSet(t);
+          subTabDragStartRef.current = t;
+          isDraggingSubTabRef.current = true;
         },
         scrollLeft: scrollLeft,
         canvasRedrawCount: canvasRedrawCount
-      }), /*#__PURE__*/React.createElement("div", {
+      })), /*#__PURE__*/React.createElement("div", {
         className: "flex-1 flex flex-col relative bg-[#111111] min-h-full"
       }, vTrack && /*#__PURE__*/React.createElement("div", {
         style: {
@@ -16443,10 +16746,12 @@ const App = () => {
     "data-lucide": "keyboard",
     className: "w-3 h-3 text-zinc-600"
   })), " Ctrl+Scroll: Playhead"))), contextMenu && (contextMenu.isSubTab ? /*#__PURE__*/React.createElement("div", {
-    className: "fixed z-[60] bg-[#2a2a2a] border border-zinc-700 rounded-lg shadow-2xl py-1 w-64",
+    className: "fixed z-[60] bg-[#2a2a2a] border border-zinc-700 rounded-lg shadow-2xl py-1 w-64 overflow-y-auto",
     style: {
-      left: contextMenu.x,
-      top: contextMenu.y
+      left: Math.min(contextMenu.x, window.innerWidth - 260),
+      top: contextMenu.y + 200 > window.innerHeight ? undefined : contextMenu.y,
+      bottom: contextMenu.y + 200 > window.innerHeight ? (window.innerHeight - contextMenu.y) : undefined,
+      maxHeight: '60vh'
     },
     onClick: e => e.stopPropagation()
   }, /*#__PURE__*/React.createElement("div", {
@@ -16531,10 +16836,12 @@ const App = () => {
   }, "Loop Selection 4 times"), /*#__PURE__*/React.createElement("span", {
     className: "text-purple-400 text-xs font-semibold font-mono ml-auto"
   }, "Ctrl+L"))) : /*#__PURE__*/React.createElement("div", {
-    className: "fixed z-[60] bg-[#2a2a2a] border border-zinc-700 rounded-lg shadow-2xl py-1 w-64",
+    className: "fixed z-[60] bg-[#2a2a2a] border border-zinc-700 rounded-lg shadow-2xl py-1 w-64 overflow-y-auto",
     style: {
-      left: contextMenu.x,
-      top: contextMenu.y
+      left: Math.min(contextMenu.x, window.innerWidth - 260),
+      top: contextMenu.y + 260 > window.innerHeight ? undefined : contextMenu.y,
+      bottom: contextMenu.y + 260 > window.innerHeight ? (window.innerHeight - contextMenu.y) : undefined,
+      maxHeight: '60vh'
     },
     onClick: e => e.stopPropagation()
   }, contextMenu.sectionId ? /*#__PURE__*/React.createElement("button", {
@@ -16802,64 +17109,42 @@ const App = () => {
   }, /*#__PURE__*/React.createElement("div", {
     className: "bg-[#262626] border border-[#383838] rounded-xl shadow-2xl w-full max-w-md p-5 text-slate-200",
     onClick: e => e.stopPropagation()
-  }, synthCategory === 'soundfont' ? (
-    /*#__PURE__*/React.createElement(React.Fragment, null,
-      /*#__PURE__*/React.createElement("div", { className: "flex justify-between items-center pb-3 border-b border-[#383838]" },
-        /*#__PURE__*/React.createElement("div", null,
-          /*#__PURE__*/React.createElement("button", { onClick: () => { setSynthCategory(null); setSelectedSoundFontId(null); }, className: "text-[10px] text-cyan-400 hover:text-cyan-300 mr-2" }, "\u2190 Back"),
-          /*#__PURE__*/React.createElement("h3", { className: "text-sm font-bold inline text-amber-400" }, "Select Instrument")
-        ),
-        /*#__PURE__*/React.createElement("button", { onClick: closeInstrumentSelector, className: "text-slate-400 hover:text-slate-200" }, "\u2715")
-      ),
-      /*#__PURE__*/React.createElement("p", { className: "text-[10px] text-zinc-500 mt-2 mb-2" }, "SoundFont: ", selectedSoundFontId),
-      /*#__PURE__*/React.createElement("div", { className: "mt-2 max-h-72 overflow-y-auto space-y-0.5" },
-        /*#__PURE__*/React.createElement("button", {
-          onClick: () => setTrackInstrumentWithProgram(instrumentSelectorTrackId, selectedSoundFontId),
-          className: "w-full text-left px-3 py-1.5 text-xs rounded bg-zinc-800 hover:bg-zinc-700 text-zinc-400"
-  }, "None (Default Program)"),
-        sfPresets === null ? (
-          React.createElement("p", { className: "text-[10px] text-zinc-500 py-2" }, "Loading instruments...")
-        ) : sfPresets.length > 0 ? (
-          React.createElement("div", { className: "grid grid-cols-2 gap-0.5" },
-            sfPresets.map((p, i) => React.createElement("button", {
+  },
+    /*#__PURE__*/React.createElement("div", { className: "flex justify-between items-center pb-3 border-b border-[#383838]" },
+      /*#__PURE__*/React.createElement("h3", { className: "text-sm font-bold text-amber-400" }, "Select Instrument"),
+      /*#__PURE__*/React.createElement("button", { onClick: closeInstrumentSelector, className: "text-slate-400 hover:text-slate-200" }, "\u2715")
+    ),
+    /*#__PURE__*/React.createElement("input", {
+      type: "text",
+      placeholder: "T\u00ecm nh\u1ea1c c\u1ee5...",
+      value: sfPresetSearchQuery,
+      onChange: e => setSfPresetSearchQuery(e.target.value),
+      autoFocus: true,
+      className: "w-full bg-black border border-zinc-700 rounded px-2 py-1.5 text-xs outline-none my-3"
+    }),
+    /*#__PURE__*/React.createElement("div", { className: "max-h-72 overflow-y-auto space-y-0.5" },
+      /*#__PURE__*/React.createElement("button", {
+        onClick: () => setTrackInstrumentWithProgram(instrumentSelectorTrackId, null),
+        className: "w-full text-left px-3 py-1.5 text-xs rounded bg-zinc-800 hover:bg-zinc-700 text-zinc-400 mb-1"
+      }, "None (Default Synth)"),(
+      sfPresets === null ? (
+        /*#__PURE__*/React.createElement("p", { className: "text-[10px] text-zinc-500 py-2" }, "Loading instruments...")
+      ) : sfPresets.length > 0 ? (
+        /*#__PURE__*/React.createElement("div", { className: "space-y-0.5" },
+          sfPresets
+            .filter(p => !sfPresetSearchQuery || (p.name || '').toLowerCase().includes(sfPresetSearchQuery.toLowerCase()) || (p._sfName || '').toLowerCase().includes(sfPresetSearchQuery.toLowerCase()))
+            .map((p, i) => /*#__PURE__*/React.createElement("button", {
               key: i,
-              onClick: () => setTrackInstrumentWithProgram(instrumentSelectorTrackId, selectedSoundFontId, p.program, p.name || 'Preset ' + p.program),
-              className: "text-left px-2 py-1 text-[10px] rounded bg-zinc-800/60 hover:bg-amber-800 text-zinc-300 truncate"
-            }, p.name || 'Preset ' + p.program)
-          ))
-        ) : (
-          React.createElement("p", { className: "text-[10px] text-zinc-500 py-2" }, "No presets found.")
+              onClick: () => setTrackInstrumentWithProgram(instrumentSelectorTrackId, p._sfId, p.program, p.name || 'Preset ' + p.program, p.bank),
+              className: "w-full text-left px-2 py-1 text-[10px] rounded bg-zinc-800/60 hover:bg-amber-800 text-zinc-300 truncate flex items-center gap-2"
+            },
+              /*#__PURE__*/React.createElement("span", { className: "text-[9px] text-zinc-500 shrink-0" }, p._sfDisplay),
+              p.bank === 128 ? /*#__PURE__*/React.createElement("span", { className: "mr-1" }, "🥁") : null,
+              p.name || 'Preset ' + p.program
+            ))
         )
-      )
-    )
-  ) : (
-    /*#__PURE__*/React.createElement(React.Fragment, null,
-      /*#__PURE__*/React.createElement("div", { className: "flex justify-between items-center pb-3 border-b border-[#383838]" },
-        /*#__PURE__*/React.createElement("h3", { className: "text-sm font-bold text-violet-400" }, "Synth Selector")
-      ),
-      /*#__PURE__*/React.createElement("div", { className: "mt-3 max-h-80 overflow-y-auto space-y-1" },
-        /*#__PURE__*/React.createElement("button", {
-          onClick: () => setTrackInstrumentWithProgram(instrumentSelectorTrackId, null),
-          className: "w-full text-left px-3 py-2 text-xs rounded bg-zinc-800 hover:bg-zinc-700 text-zinc-400"
-        }, "None (Default Synth)"),
-        /*#__PURE__*/React.createElement("div", { className: "text-[10px] text-zinc-500 mt-2 mb-1 uppercase font-bold" }, "SoundFonts"),
-        instrumentSelectorData?.soundfonts?.map((sf, i) =>
-          /*#__PURE__*/React.createElement("button", {
-            key: "sf_" + i,
-            onClick: () => setTrackInstrument(instrumentSelectorTrackId, "sf_" + sf.id, sf.display || sf.name || sf.id),
-            className: "w-full text-left px-3 py-2 text-xs rounded bg-zinc-800 hover:bg-amber-800 text-zinc-200 flex items-center justify-between"
-          }, /*#__PURE__*/React.createElement("span", null, sf.display || sf.name || sf.id), /*#__PURE__*/React.createElement("span", { className: "text-[10px] text-amber-400" }, "SoundFont"))
-        ),
-        /*#__PURE__*/React.createElement("div", { className: "text-[10px] text-zinc-500 mt-2 mb-1 uppercase font-bold" }, "VST Instruments"),
-        instrumentSelectorData?.vst_instruments?.map((v, i) =>
-          /*#__PURE__*/React.createElement("button", {
-            key: "vst_" + i,
-            onClick: () => setTrackInstrumentWithProgram(instrumentSelectorTrackId, v.id, undefined, v.name || v.id),
-            className: "w-full text-left px-3 py-2 text-xs rounded bg-zinc-800 hover:bg-violet-900 text-zinc-200 flex items-center justify-between"
-          }, /*#__PURE__*/React.createElement("span", null, v.name || v.id), /*#__PURE__*/React.createElement("span", { className: "text-[10px] text-cyan-400" }, v.type))
-        ),
-        (!instrumentSelectorData || (!instrumentSelectorData.vst_instruments?.length && !instrumentSelectorData.soundfonts?.length)) &&
-          /*#__PURE__*/React.createElement("p", { className: "text-xs text-zinc-500 py-4 text-center" }, "No plugins available. Upload SoundFont via Tools \u2192 Plugin Manager.")
+      ) : (
+        /*#__PURE__*/React.createElement("p", { className: "text-[10px] text-zinc-500 py-2" }, sfPresetSearchQuery ? "Kh\u00f4ng t\u00ecm th\u1ea5y nh\u1ea1c c\u1ee5 ph\u00f9 h\u1ee3p." : "No presets found.")
       )
     )
   ))), fxSelectorTrackId && /*#__PURE__*/React.createElement("div", {

app/static/js/services/aiGateway.js

@@ -48,7 +48,7 @@ const AIGateway = (function() {
     name: 'fade_out', description: 'Fade-out clip (0.5s đến max)', parameters: { type: 'object', properties: { track_id: { type: 'string' }, duration_seconds: { type: 'number' }, clip_index: { type: 'number', description: 'Chỉ số của clip trên track (1-based, ví dụ: 1 cho clip 1, 2 cho clip 2)' }, clip_id: { type: 'string', description: 'ID của clip cụ thể' } } }
   }, {
     name: 'generate_multitrack_midi',
-    description: 'Generates multi-track MIDI data based on genre, bar duration, and requested instruments list.',
+    description: 'Generates multi-track MIDI data along with SoundFont Program configurations for each track.',
     parameters: {
       type: 'object',
       properties: {
@@ -57,12 +57,15 @@ const AIGateway = (function() {
         total_bars: { type: 'integer' },
         tracks: {
           type: 'array',
-          description: 'Array of instrument tracks along with their corresponding MIDI notes',
+          description: 'Array of instrument tracks with MIDI notes and SoundFont instrument selection',
           items: {
             type: 'object',
             properties: {
               track_name: { type: 'string', description: 'Track name (e.g., String Ensemble, Epic Brass, Taiko Drums)' },
               instrument_type: { type: 'string', enum: ['STRINGS', 'BRASS', 'SYNTH', 'PERCUSSION', 'DRUMS'] },
+              soundfont_id: { type: 'string', description: "ID of the SoundFont to use (e.g. 'generaluser_gs')" },
+              soundfont_bank: { type: 'integer', default: 0, description: 'MIDI Bank code: 0 for melodic instruments, 128 for Drums/Percussion' },
+              soundfont_program: { type: 'integer', description: 'MIDI Program Number 0-127 matching the instrument name in the SoundFont catalog' },
               notes: {
                 type: 'array',
                 items: {
@@ -77,7 +80,7 @@ const AIGateway = (function() {
                 }
               }
             },
-            required: ['track_name', 'instrument_type', 'notes']
+            required: ['track_name', 'instrument_type', 'soundfont_id', 'soundfont_bank', 'soundfont_program', 'notes']
           }
         }
       },
@@ -176,13 +179,29 @@ const AIGateway = (function() {
     return calls;
   }
 
+  function buildCatalogPromptSection() {
+    const catalog = window.__soundfontCatalog;
+    if (!catalog || !catalog.condensed_catalog) return '';
+    const lines = [];
+    for (const [sfId, info] of Object.entries(catalog.condensed_catalog)) {
+      lines.push(`SoundFont ID: '${sfId}' (File: ${info.filename}):`);
+      for (const inst of info.instruments || []) {
+        lines.push(`  - ${inst.name}: bank=${inst.bank}, program=${inst.program}`);
+      }
+    }
+    if (lines.length === 0) return '';
+    return `\n=== SOUNDFONT INSTRUMENT CATALOG ===\nYou have the following SoundFont instruments available on the system:\n${lines.join('\n')}\n\nMANDATORY RULES WHEN CREATING TRACKS WITH generate_multitrack_midi:\n1. You MUST look up the catalog above and fill in the correct soundfont_id, soundfont_bank, and soundfont_program for each track.\n2. Melodic instruments (Piano, Strings, Brass, etc.) MUST use soundfont_bank=0.\n3. Drums and Percussion MUST use soundfont_bank=128.\n4. Example: For \"Brass horns\", use soundfont_id="generaluser_gs", soundfont_bank=0, soundfont_program=56.\n5. Example: For \"Drum kit\", use soundfont_id="generaluser_gs", soundfont_bank=128, soundfont_program=0.\n`;
+  }
+
   function buildUserMessage(prompt, context, systemInstruction = '') {
     const contextStr = JSON.stringify(context, null, 2);
     const toolNames = DEFAULT_TOOLS.map(t => `  - ${t.name}: ${t.description}`).join('\n');
+    const catalogSection = buildCatalogPromptSection();
     return [
       { role: 'system', content: `Bạn là trợ lý điều khiển DAW chuyên nghiệp.
 Nhiệm vụ của bạn là phân tích yêu cầu của người dùng và chuyển đổi thành danh sách các function calls tương ứng.
 ${systemInstruction ? `\nHướng dẫn tạo nhạc đặc biệt từ Preset:\n${systemInstruction}\n` : ''}
+${catalogSection}
 QUAN TRỌNG:
 1. Bạn đang hoạt động ở chế độ một lượt (one-shot). Hãy trả về TẤT CẢ các function calls cần thiết để thực hiện toàn bộ các bước trong yêu cầu của người dùng trong một phản hồi duy nhất. Đừng thực hiện từng bước qua nhiều lượt chat.
 2. Có thể gọi nhiều function cùng một lúc (gọi song song/nối tiếp). Chúng sẽ được thực thi theo thứ tự bạn trả về.
@@ -199,6 +218,7 @@ Ví dụ: "Hãy chọn và copy từ bar 4 đến bar 12 của track 1 sau đó
   function buildAIPromptContext(dawState) {
     const tracks = (dawState.tracks || []).map(t => {
       const clips = t.clips && t.clips.length > 0 ? t.clips : (t.buffer ? [{ id: 'default_' + t.id, name: t.name, startTime: t.startTime || 0, duration: t.buffer.duration }] : []);
+      const se = t.synth_engine || null;
       return {
         id: t.id,
         name: t.name,
@@ -208,6 +228,7 @@ Ví dụ: "Hãy chọn và copy từ bar 4 đến bar 12 của track 1 sau đó
         solo: t.solo,
         volumeDb: t.volumeDb ?? 0,
         pan: t.pan ?? 0,
+        synth_engine: se ? { type: se.type, plugin_id: se.plugin_id, soundfont_bank: se.soundfont_bank, soundfont_program: se.soundfont_program, soundfont_id: se.soundfont_id } : undefined,
         clips: clips.map(c => ({ id: c.id, name: c.name, startTime: parseFloat((c.startTime || 0).toFixed(3)), duration: parseFloat((c.buffer ? c.buffer.duration : 0).toFixed(3)) }))
       };
     });

app/static/js/services/api.js

@@ -63,6 +63,7 @@ window.API_BASE_URL = window.API_BASE_URL || window.location.origin;
         savePreferences: (prefs) => apiRequest('/api/v1/user/preferences', { method: 'POST', body: JSON.stringify({ preferences: prefs }) }),
 
         listPlugins: () => apiRequest('/api/v1/plugins/available', { method: 'GET' }),
+        getSoundfontCatalog: () => apiRequest('/api/v1/plugins/soundfonts/catalog', { method: 'GET' }),
         listDefaultSoundfonts: () => apiRequest('/api/v1/plugins/default-soundfonts', { method: 'GET' }),
         listSoundfontInstruments: (sfId) => apiRequest(`/api/v1/plugins/soundfont-instruments/${sfId}`, { method: 'GET' }),
         renderProject: (projectJson, outputFilename) => apiRequest('/api/v1/plugins/render', { method: 'POST', body: JSON.stringify({ project_json: projectJson, output_filename: outputFilename }) }),

app/static/js/services/fluidsynthLoader.js

@@ -0,0 +1,37 @@
+(function () {
+  if (window.__FluidSynthReady) return;
+
+  var FLUIDSYNTH_JS_URL;
+  var FLUIDSYNTH_WASM_URL;
+
+  if (window.__FLUIDSYNTH_CDN) {
+    FLUIDSYNTH_JS_URL = window.__FLUIDSYNTH_CDN;
+  } else if (window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1') {
+    FLUIDSYNTH_JS_URL = 'https://cdn.jsdelivr.net/npm/@enikey87/fluidsynth-emscripten@0.1.1/dist/libfluidsynth-2.3.0-sf3.js';
+  } else {
+    FLUIDSYNTH_JS_URL = '/static/js/vendor/libfluidsynth-2.3.0-sf3.js';
+  }
+
+  FLUIDSYNTH_WASM_URL = FLUIDSYNTH_JS_URL.replace(/\.js$/, '.wasm');
+
+  window.__FluidSynthLocateWasm = function () { return FLUIDSYNTH_WASM_URL; };
+
+  window.__FluidSynthReady = new Promise(function (resolve) {
+    var script = document.createElement('script');
+    script.type = 'module';
+    script.textContent = [
+      'import FluidsynthModule from "' + FLUIDSYNTH_JS_URL + '";',
+      'window.__FluidSynthModuleFactory = FluidsynthModule;',
+      'console.log("[FluidSynth] Loaded:", "' + FLUIDSYNTH_JS_URL + '");'
+    ].join('\n');
+    document.head.appendChild(script);
+
+    var check = setInterval(function () {
+      if (window.__FluidSynthModuleFactory) {
+        clearInterval(check);
+        resolve();
+      }
+    }, 50);
+    setTimeout(function () { clearInterval(check); resolve(); }, 15000);
+  });
+})();

app/static/js/services/soundfontPlayer.js

@@ -1,18 +1,36 @@
-// SonicForge Studio SoundFont Player Service
 (function () {
-    'use strict';
+    const RENDER_BLOCK = 512;
+    const QUEUE_TARGET = 4;
+    let _audioCtx = null;
+    let _fluidModule = null;
+    let _synthPtr = null;
+    let _settingsPtr = null;
+    let _workletNode = null;
+    let _initialized = false;
+    let _initPromise = null;
+    let _currentSfId = null;
+    let _sfHandleMap = new Map();
+    let _channels = Array.from({ length: 16 }, () => ({ bank: 0, program: 0, isPercussion: false }));
+    let _nextMelodicChannel = 0;
+    let _sustainStates = new Array(16).fill(false);
+    let _engineChMap = {};
+    let _activeNotes = {};
+    let _leftBufPtr = null;
+    let _rightBufPtr = null;
+    let _renderTimer = null;
+    let _pendingNoteTimers = [];
+    let _loadedFonts = {};
+    let _activeOscillators = {};
+    let _gainNode = null;
+    let _scheduledNotes = [];
 
-    const activeOscillators = {};
-
-    // Use the shared AudioContext from the main app (lazy init)
-    let __gainNode = null;
-    const getCtx = () => {
+    const getCtx = function () {
         if (typeof getAudioContext === 'function') {
-            const ctx = getAudioContext();
-            if (!__gainNode) {
-                __gainNode = ctx.createGain();
-                __gainNode.gain.value = 0.3;
-                __gainNode.connect(ctx.destination);
+            var ctx = getAudioContext();
+            if (!_gainNode) {
+                _gainNode = ctx.createGain();
+                _gainNode.gain.value = 0.3;
+                _gainNode.connect(ctx.destination);
             }
             return ctx;
         }
@@ -22,172 +40,475 @@
         if (window.__sharedAudioCtx.state === 'suspended') {
             window.__sharedAudioCtx.resume();
         }
-        if (!__gainNode) {
-            __gainNode = window.__sharedAudioCtx.createGain();
-            __gainNode.gain.value = 0.3;
-            __gainNode.connect(window.__sharedAudioCtx.destination);
+        if (!_gainNode) {
+            _gainNode = window.__sharedAudioCtx.createGain();
+            _gainNode.gain.value = 0.3;
+            _gainNode.connect(window.__sharedAudioCtx.destination);
         }
         return window.__sharedAudioCtx;
     };
 
     const SonicSF = {
-        loadedFonts: {},
+        loadedFonts: _loadedFonts,
 
-        // Load SoundFont from URL → ArrayBuffer → store in memory
-        loadSoundFont: async function (url) {
-            if (this.loadedFonts[url]) return this.loadedFonts[url];
-            const resp = await fetch(url);
-            if (!resp.ok) throw new Error('Failed to load SoundFont: ' + url);
-            const buffer = await resp.arrayBuffer();
-            this.loadedFonts[url] = buffer;
-            return buffer;
+        init: async function (audioContext) {
+            if (_initialized && _fluidModule) return;
+            if (_initPromise) return _initPromise;
+            _initPromise = (async () => {
+                if (!window.__FluidSynthModuleFactory) {
+                    console.log("[SonicSF] Waiting for FluidSynth WASM module to load...");
+                    await window.__FluidSynthReady;
+                    if (!window.__FluidSynthModuleFactory) {
+                        console.warn("[SonicSF] FluidSynth WASM still not available after waiting.");
+                        _initPromise = null;
+                        return;
+                    }
+                }
+                try {
+                    _audioCtx = audioContext;
+                    if (_audioCtx.state === 'suspended') await _audioCtx.resume();
+
+                    console.log("[SonicSF] AudioCtx state:", _audioCtx.state, "sampleRate:", _audioCtx.sampleRate);
+
+                    var _useScriptNode = true;
+                    try {
+                        await _audioCtx.audioWorklet.addModule('/static/js/worklets/fluidsynth-bridge.js');
+                        console.log("[SonicSF] Worklet registered OK");
+                    } catch (e) {
+                        console.warn("[SonicSF] Worklet reg failed:", e);
+                    }
+                    console.log("[SonicSF] Using ScriptProcessorNode (forced for debug)");
+
+                    console.log("[SonicSF] Initializing FluidSynth WASM Engine...");
+                    var TOTAL_MEMORY = 256 * 1024 * 1024;
+                    _fluidModule = await window.__FluidSynthModuleFactory({
+                        locateFile: function (path) {
+                            if (path.endsWith('.wasm')) {
+                                return window.__FluidSynthLocateWasm ? window.__FluidSynthLocateWasm() : path;
+                            }
+                            return path;
+                        },
+                        TOTAL_MEMORY: TOTAL_MEMORY,
+                        printErr: function (msg) {
+                            console.warn('[FluidSynth:err]', msg);
+                        }
+                    });
+
+                    if (!_fluidModule || !_fluidModule._new_fluid_settings) {
+                        throw new Error("FluidSynth WASM module loaded but API missing");
+                    }
+
+                    _settingsPtr = _fluidModule._new_fluid_settings();
+                    _fluidModule._fluid_settings_setnum(_settingsPtr, "synth.sample-rate", _audioCtx.sampleRate || 44100);
+                    _fluidModule._fluid_settings_setnum(_settingsPtr, "synth.gain", 2.0);
+                    _fluidModule._fluid_settings_setnum(_settingsPtr, "synth.polyphony", 256);
+                    _fluidModule._fluid_settings_setint(_settingsPtr, "synth.verbose", 1);
+                    _fluidModule._fluid_settings_setint(_settingsPtr, "synth.ladspa.active", 0);
+                    _fluidModule._fluid_settings_setstr(_settingsPtr, "player.timing-source", "audio");
+                    console.log("[SonicSF] FluidSynth settings configured");
+
+                    _synthPtr = _fluidModule._new_fluid_synth(_settingsPtr);
+                    if (!_synthPtr) throw new Error("Failed to create FluidSynth synthesizer");
+                    _fluidModule._fluid_synth_set_gain(_synthPtr, 1.0);
+
+                    try { _fluidModule.FS.mkdir('/soundfonts'); } catch (e) {}
+
+                    _leftBufPtr = _fluidModule._malloc(RENDER_BLOCK * 4);
+                    _rightBufPtr = _fluidModule._malloc(RENDER_BLOCK * 4);
+
+                    if (!_useScriptNode) {
+                        try {
+                            _workletNode = new AudioWorkletNode(_audioCtx, 'fluidsynth-bridge');
+                            _workletNode.connect(_audioCtx.destination);
+                            console.log("[SonicSF] AudioWorklet node connected");
+                            _startRenderLoop();
+                        } catch (e) {
+                            console.warn("[SonicSF] AudioWorkletNode failed:", e);
+                            _useScriptNode = true;
+                        }
+                    }
+                    if (_useScriptNode) {
+                        var spBufSz = 2048;
+                        var spn = _audioCtx.createScriptProcessor(spBufSz, 0, 2);
+                        var lp = _fluidModule._malloc(spBufSz * 4);
+                        var rp = _fluidModule._malloc(spBufSz * 4);
+                        spn.onaudioprocess = function (e) {
+                            var left = e.outputBuffer.getChannelData(0);
+                            var right = e.outputBuffer.getChannelData(1);
+                            var sz = left.length;
+                            try {
+                                _fluidModule._fluid_synth_write_float(_synthPtr, sz, lp, 0, 1, rp, 0, 1);
+                                var hf = _fluidModule.HEAPF32;
+                                var lpb = lp >> 2, rpb = rp >> 2;
+                                for (var si = 0; si < sz; si++) {
+                                    left[si] = hf[lpb + si];
+                                    right[si] = hf[rpb + si];
+                                }
+                            } catch (er) {}
+                        };
+                        spn.connect(_audioCtx.destination);
+                        _workletNode = spn;
+                        console.log("[SonicSF] ScriptProcessorNode fallback active (buf:", spBufSz, ")");
+                    }
+
+                    _initialized = true;
+                    console.log("[SonicSF] FluidSynth WASM Engine initialized.");
+                } catch (e) {
+                    console.error("[SonicSF] FluidSynth init failed:", e);
+                    _initPromise = null;
+                    _cleanupFluid();
+                }
+            })();
+            return _initPromise;
         },
 
-        playNote: function (note, velocity, durationMs, startTime, program, destinationNode) {
-            const ctx = getCtx();
-            const freq = 440 * Math.pow(2, (note - 69) / 12);
-            if (freq <= 0 || isNaN(freq)) return null;
-
-            const osc = ctx.createOscillator();
-            const noteGain = ctx.createGain();
-
-            // Default settings
-            let oscType = 'triangle';
-            let attackTime = 0.03;
-            let decayTime = 0.1;
-            let sustainLevel = 0.5;
-            let releaseTime = 0.2;
-            let volFactor = 0.25;
-
-            const prog = program !== undefined ? parseInt(program) : 0;
-            if (prog >= 0 && prog <= 7) { // Pianos
-                oscType = 'sine';
-                decayTime = 0.3;
-                sustainLevel = 0.1;
-                releaseTime = 0.2;
-            } else if (prog >= 8 && prog <= 15) { // Chromatic Perc
-                oscType = 'sine';
-                decayTime = 0.1;
-                sustainLevel = 0.0;
-                releaseTime = 0.1;
-            } else if (prog >= 16 && prog <= 23) { // Organs
-                oscType = 'sine';
-                attackTime = 0.05;
-                sustainLevel = 0.8;
-                releaseTime = 0.1;
-            } else if (prog >= 24 && prog <= 31) { // Guitars
-                oscType = 'triangle';
-                decayTime = 0.4;
-                sustainLevel = 0.2;
-                releaseTime = 0.3;
-            } else if (prog >= 32 && prog <= 39) { // Basses
-                oscType = 'triangle';
-                attackTime = 0.02;
-                decayTime = 0.2;
-                sustainLevel = 0.6;
-                releaseTime = 0.2;
-            } else if (prog >= 40 && prog <= 47) { // Strings
-                oscType = 'sawtooth';
-                attackTime = 0.15;
-                sustainLevel = 0.8;
-                releaseTime = 0.5;
-                volFactor = 0.15;
-            } else if (prog >= 48 && prog <= 55) { // Ensemble / Choir
-                oscType = 'sawtooth';
-                attackTime = 0.2;
-                sustainLevel = 0.8;
-                releaseTime = 0.6;
-                volFactor = 0.12;
-            } else if (prog >= 56 && prog <= 63) { // Brass
-                oscType = 'sawtooth';
-                attackTime = 0.08;
-                sustainLevel = 0.7;
-                releaseTime = 0.3;
-                volFactor = 0.15;
-            } else if (prog >= 64 && prog <= 71) { // Reed
-                oscType = 'square';
-                attackTime = 0.05;
-                sustainLevel = 0.6;
-                releaseTime = 0.2;
-                volFactor = 0.15;
-            } else if (prog >= 72 && prog <= 79) { // Pipe
-                oscType = 'sine';
-                attackTime = 0.1;
-                sustainLevel = 0.7;
-                releaseTime = 0.3;
-                volFactor = 0.2;
-            } else if (prog >= 80 && prog <= 119) { // Synth Lead/Pad/FX
-                oscType = 'sawtooth';
-                attackTime = 0.05;
-                sustainLevel = 0.6;
-                releaseTime = 0.4;
-                volFactor = 0.15;
+        _allocCStr: function (str) {
+            var ptr = _fluidModule._malloc(str.length + 1);
+            for (var i = 0; i < str.length; i++) {
+                _fluidModule.HEAPU8[ptr + i] = str.charCodeAt(i);
             }
+            _fluidModule.HEAPU8[ptr + str.length] = 0;
+            return ptr;
+        },
 
+        _tryLoadSFL: function (buf, ext) {
+            var fname = '/' + ext + '_' + Date.now();
+            try { _fluidModule.FS.unlink(fname); } catch (e) {}
+            _fluidModule.FS.writeFile(fname, new Uint8Array(buf));
+            var cPath = this._allocCStr(fname);
+            var handle = _fluidModule._fluid_synth_sfload(_synthPtr, cPath, 1);
+            _fluidModule._free(cPath);
+            try { _fluidModule.FS.unlink(fname); } catch (e) {}
+            return handle;
+        },
+
+        loadSoundFont: async function (sfId) {
+            if (!_initialized || !_fluidModule) return false;
+            if (_currentSfId === sfId) return true;
+            if (_sfHandleMap.has(sfId)) {
+                _currentSfId = sfId;
+                return true;
+            }
+            try {
+                var cache = window.SonicSFStorage;
+                var buf = cache ? await cache.getBuffer(sfId) : null;
+                if (!buf) {
+                    var url = "/api/v1/plugins/soundfonts/download/" + encodeURIComponent(sfId) + "?t=" + Date.now();
+                    var resp = await fetch(url);
+                    if (!resp.ok) {
+                        console.warn("[SonicSF] SoundFont not found:", sfId);
+                        return false;
+                    }
+                    buf = await resp.arrayBuffer();
+                    if (cache) await cache.saveBuffer(sfId, buf);
+                }
+                var sfHandle = this._tryLoadSFL(buf, '.sf3');
+                if (sfHandle === -1) {
+                    console.warn("[SonicSF] sfload .sf3 failed, trying .sf2 for", sfId);
+                    sfHandle = this._tryLoadSFL(buf, '.sf2');
+                }
+                if (sfHandle === -1) {
+                    console.error("[SonicSF] FluidSynth failed to parse SoundFont:", sfId);
+                    return false;
+                }
+                _sfHandleMap.set(sfId, sfHandle);
+                _currentSfId = sfId;
+                _loadedFonts[sfId] = true;
+                console.log("[SonicSF] SoundFont loaded:", sfId, "handle:", sfHandle);
+                return true;
+            } catch (e) {
+                console.warn("[SonicSF] loadSoundFont error:", e);
+                return false;
+            }
+        },
+
+        selectInstrument: async function (channel, bank, program, sfId) {
+            if (!_initialized || !_fluidModule) {
+                var ctx = new (window.AudioContext || window.webkitAudioContext)();
+                await this.init(ctx);
+            }
+            if (sfId) {
+                var ok = await this.loadSoundFont(sfId);
+                if (!ok) return;
+            }
+            var engKey = (sfId || '') + ':' + bank + ':' + program;
+            if (!_engineChMap[engKey]) {
+                var allocCh = this.allocateChannel(bank);
+                _engineChMap[engKey] = allocCh;
+                channel = allocCh;
+            } else {
+                channel = _engineChMap[engKey];
+            }
+            var sfHandle = _sfHandleMap.get(sfId);
+            if (sfHandle !== undefined) {
+                try {
+                    _fluidModule._fluid_synth_program_select(_synthPtr, channel, sfHandle, bank, program);
+                } catch (e) {}
+            } else {
+                try { _fluidModule._fluid_synth_bank_select(_synthPtr, channel, bank); } catch (e) {}
+                try { _fluidModule._fluid_synth_program_change(_synthPtr, channel, program); } catch (e) {}
+            }
+            _channels[channel].bank = bank;
+            _channels[channel].program = program;
+            _channels[channel].isPercussion = (bank === 128);
+        },
+
+        controllerChange: function (channel, controller, value) {
+            if (channel < 0 || channel > 15) return;
+            if (_initialized && _fluidModule) {
+                try {
+                    _fluidModule._fluid_synth_cc(_synthPtr, channel, controller, value);
+                } catch (e) {}
+            }
+            if (controller === 0) {
+                _channels[channel].bank = value;
+                _channels[channel].isPercussion = (value === 128);
+            }
+            if (controller === 64) {
+                _sustainStates[channel] = value >= 64;
+            }
+        },
+
+        programChange: function (channel, program) {
+            if (channel < 0 || channel > 15) return;
+            if (_initialized && _fluidModule) {
+                try {
+                    _fluidModule._fluid_synth_program_change(_synthPtr, channel, program);
+                } catch (e) {}
+            }
+            _channels[channel].program = program;
+        },
+
+        allocateChannel: function (bank) {
+            if (bank === 128) return 9;
+            var ch = _nextMelodicChannel % 9;
+            _nextMelodicChannel = (_nextMelodicChannel + 1) % 9;
+            return ch;
+        },
+
+        applyAITrackInstrument: function (bank, program, synthEngine) {
+            if (synthEngine) {
+                bank = bank !== undefined ? bank : (synthEngine.soundfont_bank || 0);
+                program = program !== undefined ? program : (synthEngine.soundfont_program || 0);
+            }
+            var sfId = synthEngine && synthEngine.soundfont_id;
+            var engKey = (sfId || '') + ':' + bank + ':' + program;
+            if (!_engineChMap[engKey]) {
+                var channel = this.allocateChannel(bank);
+                _engineChMap[engKey] = channel;
+            }
+            this.selectInstrument(_engineChMap[engKey], bank, program, sfId);
+            return _engineChMap[engKey];
+        },
+
+        getChannelState: function (channel) {
+            if (channel < 0 || channel > 15) return null;
+            return { bank: _channels[channel].bank, program: _channels[channel].program, isPercussion: _channels[channel].isPercussion };
+        },
+
+        sustainActive: function (channel) {
+            if (channel < 0 || channel > 15) return false;
+            return _sustainStates[channel];
+        },
+
+        pitchBend: function (channel, value) {
+            if (channel < 0 || channel > 15) return;
+            if (_initialized && _fluidModule) {
+                try {
+                    _fluidModule._fluid_synth_pitch_bend(_synthPtr, channel, value);
+                } catch (e) {}
+            }
+        },
+
+        stopNote: function (channel, pitch) {
+            if (channel < 0 || channel > 15) return;
+            if (_initialized && _fluidModule) {
+                var key = channel + ':' + pitch;
+                var mappedChs = _activeNotes[key];
+                if (mappedChs === undefined) mappedChs = [channel];
+                for (var i = 0; i < mappedChs.length; i++) {
+                    try { _fluidModule._fluid_synth_noteoff(_synthPtr, mappedChs[i], pitch); } catch (e) {}
+                }
+                delete _activeNotes[key];
+            }
+        },
+
+        playNote: function (note, velocity, durationMs, startTime, program, destinationNode, channel, synthEngine) {
+            if (!_initialized || !_fluidModule) {
+                this._lazyInit();
+                this._playNoteFallback(note, velocity, 2000, startTime, program, destinationNode, channel, synthEngine);
+                return;
+            }
+            this._playNoteFluid(note, velocity, durationMs, startTime, program, channel, synthEngine);
+        },
+
+        _lazyInit: async function () {
+            if (_initialized && _fluidModule) return;
+            if (_initPromise) return;
+            try {
+                var ctx = new (window.AudioContext || window.webkitAudioContext)();
+                if (ctx.state === 'suspended') await ctx.resume();
+                await this.init(ctx);
+            } catch (e) {}
+        },
+
+        _playNoteFluid: function (note, velocity, durationMs, startTime, program, channel, synthEngine) {
+            var midiPitch = Math.min(127, Math.max(0, parseInt(note) || 60));
+            var midiVel = Math.min(127, Math.max(1, Math.floor(
+                typeof velocity === 'number' ? (velocity > 1 ? velocity : velocity * 127) : 100
+            )));
+            var _origChannel = channel;
+            var ch = channel;
+            var usedBank = 0, usedProg = 0;
+            if (synthEngine) {
+                usedBank = synthEngine.soundfont_bank || 0;
+                usedProg = synthEngine.soundfont_program || 0;
+                var engKey = (synthEngine.soundfont_id || '') + ':' + usedBank + ':' + usedProg;
+                var mappedCh = _engineChMap[engKey];
+                if (mappedCh !== undefined) {
+                    ch = mappedCh;
+                } else if (ch === undefined) {
+                    ch = usedBank === 128 ? 9 : 0;
+                }
+                if (ch === undefined) ch = (usedBank === 128 ? 9 : 0);
+                var sfHandle = synthEngine.soundfont_id ? _sfHandleMap.get(synthEngine.soundfont_id) : undefined;
+                if (sfHandle !== undefined) {
+                    try {
+                        _fluidModule._fluid_synth_program_select(_synthPtr, ch, sfHandle, usedBank, usedProg);
+                    } catch (e) {}
+                } else {
+                    try { _fluidModule._fluid_synth_bank_select(_synthPtr, ch, usedBank); } catch (e) {}
+                    try { _fluidModule._fluid_synth_program_change(_synthPtr, ch, usedProg); } catch (e) {}
+                }
+            } else if (program !== undefined) {
+                usedProg = program;
+                if (ch === undefined) ch = 0;
+                try {
+                    _fluidModule._fluid_synth_program_change(_synthPtr, ch, usedProg);
+                } catch (e) {}
+            }
+            if (ch === undefined) ch = (usedBank === 128 ? 9 : 0);
+            var ctx = getCtx();
+            var now = ctx.currentTime;
+            var delay = (typeof startTime === 'number' && startTime > now) ? (startTime - now) : 0;
+            var durSec = (durationMs || 500) / 1000;
+            var scheduledNote = { on: null, off: null };
+            var self = this;
+            var doNote = function () {
+                try {
+                    console.log("[SonicSF] noteOn ch:", ch, "pitch:", midiPitch, "vel:", midiVel);
+                    _fluidModule._fluid_synth_noteon(_synthPtr, ch, midiPitch, midiVel);
+                    var noteMapKey = (_origChannel !== undefined ? _origChannel : 0) + ':' + midiPitch;
+                    if (!_activeNotes[noteMapKey]) _activeNotes[noteMapKey] = [];
+                    if (_activeNotes[noteMapKey].indexOf(ch) === -1) _activeNotes[noteMapKey].push(ch);
+                    if (durationMs > 0 && durationMs < 60000) {
+                        scheduledNote.off = setTimeout(function () {
+                            try {
+                                _fluidModule._fluid_synth_noteoff(_synthPtr, ch, midiPitch);
+                                var arr = _activeNotes[noteMapKey];
+                                if (arr) {
+                                    var idx = arr.indexOf(ch);
+                                    if (idx >= 0) arr.splice(idx, 1);
+                                    if (arr.length === 0) delete _activeNotes[noteMapKey];
+                                }
+                            } catch (e) {}
+                        }, durSec * 1000);
+                    }
+                } catch (e) {
+                    console.warn("[SonicSF] FluidSynth noteOn error:", e);
+                    self._playNoteFallback(note, velocity, durationMs, startTime, program, null, channel, synthEngine);
+                }
+            };
+            if (delay > 0) {
+                scheduledNote.on = setTimeout(doNote, delay * 1000);
+                _scheduledNotes.push(scheduledNote);
+            } else {
+                doNote();
+            }
+        },
+
+        _playNoteFallback: function (note, velocity, durationMs, startTime, program, destinationNode, channel, synthEngine) {
+            var ctx = getCtx();
+            var freq = 440 * Math.pow(2, (note - 69) / 12);
+            if (freq <= 0 || isNaN(freq)) return null;
+            if (synthEngine) {
+                var ch = channel !== undefined ? channel : (synthEngine.soundfont_bank === 128 ? 9 : 0);
+                this.controllerChange(ch, 0, synthEngine.soundfont_bank || 0);
+                this.programChange(ch, synthEngine.soundfont_program || 0);
+                if (channel === undefined) channel = ch;
+                if (program === undefined) program = synthEngine.soundfont_program;
+            }
+            var osc = ctx.createOscillator();
+            var noteGain = ctx.createGain();
+            var oscType = 'triangle';
+            var attackTime = 0.03, decayTime = 0.1, sustainLevel = 0.5, releaseTime = 0.2, volFactor = 0.25;
+            var prog = program !== undefined ? parseInt(program) : 0;
+            if (channel !== undefined && channel >= 0 && channel < 16) {
+                prog = _channels[channel].program || prog;
+            }
+            if (prog >= 0 && prog <= 7) { oscType = 'sine'; decayTime = 0.3; sustainLevel = 0.1; releaseTime = 0.2; }
+            else if (prog >= 8 && prog <= 15) { oscType = 'sine'; decayTime = 0.1; sustainLevel = 0.0; releaseTime = 0.1; }
+            else if (prog >= 16 && prog <= 23) { oscType = 'sine'; attackTime = 0.05; sustainLevel = 0.8; releaseTime = 0.1; }
+            else if (prog >= 24 && prog <= 31) { oscType = 'triangle'; decayTime = 0.4; sustainLevel = 0.2; releaseTime = 0.3; }
+            else if (prog >= 32 && prog <= 39) { oscType = 'triangle'; attackTime = 0.02; decayTime = 0.2; sustainLevel = 0.6; releaseTime = 0.2; }
+            else if (prog >= 40 && prog <= 47) { oscType = 'sawtooth'; attackTime = 0.15; sustainLevel = 0.8; releaseTime = 0.5; volFactor = 0.15; }
+            else if (prog >= 48 && prog <= 55) { oscType = 'sawtooth'; attackTime = 0.2; sustainLevel = 0.8; releaseTime = 0.6; volFactor = 0.12; }
+            else if (prog >= 56 && prog <= 63) { oscType = 'sawtooth'; attackTime = 0.08; sustainLevel = 0.7; releaseTime = 0.3; volFactor = 0.15; }
+            else if (prog >= 64 && prog <= 71) { oscType = 'square'; attackTime = 0.05; sustainLevel = 0.6; releaseTime = 0.2; volFactor = 0.15; }
+            else if (prog >= 72 && prog <= 79) { oscType = 'sine'; attackTime = 0.1; sustainLevel = 0.7; releaseTime = 0.3; volFactor = 0.2; }
+            else if (prog >= 80 && prog <= 119) { oscType = 'sawtooth'; attackTime = 0.05; sustainLevel = 0.6; releaseTime = 0.4; volFactor = 0.15; }
             osc.type = oscType;
             osc.frequency.setValueAtTime(freq, 0);
-
-            const startAt = startTime !== undefined ? startTime : ctx.currentTime;
-            const durSec = durationMs / 1000;
-
-            const vel = typeof velocity === 'number' ? (velocity > 1 ? velocity / 127 : velocity) : 0.8;
-            const targetGain = vel * volFactor;
-
-            // ADSR Envelope
+            var startAt = startTime !== undefined ? startTime : ctx.currentTime;
+            var durSec = durationMs / 1000;
+            var vel = typeof velocity === 'number' ? (velocity > 1 ? velocity / 127 : velocity) : 0.8;
+            var targetGain = vel * volFactor;
             noteGain.gain.setValueAtTime(0, startAt);
             noteGain.gain.linearRampToValueAtTime(targetGain, startAt + attackTime);
             noteGain.gain.linearRampToValueAtTime(targetGain * sustainLevel, startAt + attackTime + decayTime);
-            
-            const releaseStart = startAt + Math.max(attackTime + decayTime, durSec);
+            var releaseStart = startAt + Math.max(attackTime + decayTime, durSec);
             noteGain.gain.linearRampToValueAtTime(targetGain * sustainLevel, releaseStart);
             noteGain.gain.linearRampToValueAtTime(0, releaseStart + releaseTime);
-
             osc.connect(noteGain);
-            
-            const dest = destinationNode || __gainNode || ctx.destination;
-            noteGain.connect(dest);
-
+            noteGain.connect(destinationNode || _gainNode || ctx.destination);
             osc.start(startAt);
-            
-            const stopAt = releaseStart + releaseTime + 0.02;
+            var stopAt = releaseStart + releaseTime + 0.02;
             osc.stop(stopAt);
-
-            const oscId = `${note}_${Date.now()}_${Math.random()}`;
-            activeOscillators[oscId] = { osc, gain: noteGain };
-
-            // Clean up active oscillator reference after it stops
-            setTimeout(() => {
-                delete activeOscillators[oscId];
-            }, (stopAt - ctx.currentTime) * 1000 + 100);
-
+            var oscId = note + '_' + Date.now() + '_' + Math.random();
+            _activeOscillators[oscId] = { osc: osc, gain: noteGain };
+            setTimeout(function () { delete _activeOscillators[oscId]; }, (stopAt - ctx.currentTime) * 1000 + 100);
             return osc;
         },
 
         stopAll: function () {
-            const ctx = getCtx();
-            const now = ctx.currentTime;
-            Object.values(activeOscillators).forEach(entry => {
+            if (_initialized && _fluidModule) {
+                for (var ch = 0; ch < 16; ch++) {
+                    try { _fluidModule._fluid_synth_all_notes_off(_synthPtr, ch); } catch (e) {}
+                    try { _fluidModule._fluid_synth_all_sounds_off(_synthPtr, ch); } catch (e) {}
+                }
+            }
+            while (_scheduledNotes.length > 0) {
+                var n = _scheduledNotes.pop();
+                if (n.on) { clearTimeout(n.on); n.on = null; }
+                if (n.off) { clearTimeout(n.off); n.off = null; }
+            }
+            var ctx = getCtx();
+            var now = ctx.currentTime;
+            Object.values(_activeOscillators).forEach(function (entry) {
                 try {
-                    if (entry.gain) {
-                        entry.gain.gain.cancelScheduledValues(now);
-                        entry.gain.gain.setValueAtTime(0, now);
-                    }
-                    if (entry.osc) {
-                        try { entry.osc.stop(now); } catch (e) { }
-                    }
-                } catch (e) { }
+                    if (entry.gain) { entry.gain.gain.cancelScheduledValues(now); entry.gain.gain.setValueAtTime(0, now); }
+                    if (entry.osc) try { entry.osc.stop(now); } catch (e) {}
+                } catch (e) {}
             });
-            Object.keys(activeOscillators).forEach(k => delete activeOscillators[k]);
+            Object.keys(_activeOscillators).forEach(function (k) { delete _activeOscillators[k]; });
         },
 
-        // Save user SoundFont to IndexedDB via window.SonicStorage
         saveToIndexedDB: async function (name, arrayBuffer) {
             if (window.SonicStorage && window.SonicStorage.saveToIndexedDB) {
                 await window.SonicStorage.saveToIndexedDB('soundfont_' + name, arrayBuffer);
             }
         },
 
-        // Load user SoundFont from IndexedDB
         loadFromIndexedDB: async function (name) {
             if (window.SonicStorage && window.SonicStorage.loadFromIndexedDB) {
                 return await window.SonicStorage.loadFromIndexedDB('soundfont_' + name);
@@ -196,5 +517,76 @@
         }
     };
 
+    function _startRenderLoop() {
+        if (_renderTimer) return;
+        var Module = _fluidModule;
+        var synth = _synthPtr;
+        var node = _workletNode;
+        var leftPtr = _leftBufPtr;
+        var rightPtr = _rightBufPtr;
+        var block = RENDER_BLOCK;
+        var queueDepth = 0;
+        var maxQueue = QUEUE_TARGET;
+
+        var _dbgPeak = 0;
+        function pushFrame() {
+            if (!Module || !synth || !node) return;
+            try {
+                var lpb = leftPtr >> 2;
+                var rpb = rightPtr >> 2;
+                Module.HEAPF32.fill(0, lpb, lpb + block);
+                Module.HEAPF32.fill(0, rpb, rpb + block);
+                Module._fluid_synth_write_float(synth, block, leftPtr, 0, 1, rightPtr, 0, 1);
+                var leftArr = new Float32Array(Module.HEAPF32.subarray(lpb, lpb + block));
+                var rightArr = new Float32Array(Module.HEAPF32.subarray(rpb, rpb + block));
+                var peak = 0;
+                var avg = 0;
+                for (var si = 0; si < leftArr.length; si++) {
+                    var abs = leftArr[si] > 0 ? leftArr[si] : -leftArr[si];
+                    if (abs > peak) peak = abs;
+                    avg += abs;
+                }
+                avg /= leftArr.length;
+                if (!_dbgPeak) {
+                    _dbgPeak = 1;
+                    console.log("[SonicSF] FRAME peak:", peak.toFixed(6), "avg:", avg.toFixed(8), "gain check:", Module._fluid_synth_get_gain ? Module._fluid_synth_get_gain(synth) : 'N/A');
+                }
+                node.port.postMessage({ type: 'PCM', L: leftArr, R: rightArr }, [leftArr.buffer, rightArr.buffer]);
+                queueDepth++;
+            } catch (e) { console.warn("[SonicSF] pushFrame error:", e); }
+        }
+
+        function fillLoop() {
+            if (!Module || !synth || !node || !_initialized) {
+                _renderTimer = null;
+                return;
+            }
+            var needed = maxQueue - queueDepth;
+            for (var i = 0; i < needed; i++) {
+                pushFrame();
+            }
+            queueDepth = Math.max(0, queueDepth - 1);
+        }
+
+        _renderTimer = setInterval(fillLoop, Math.max(8, (block / _audioCtx.sampleRate) * 1000 * 0.75));
+    }
+
+    function _stopRenderLoop() {
+        if (_renderTimer) {
+            clearInterval(_renderTimer);
+            _renderTimer = null;
+        }
+    }
+
+    function _cleanupFluid() {
+        _stopRenderLoop();
+        if (_leftBufPtr && _fluidModule) { try { _fluidModule._free(_leftBufPtr); } catch (e) {} _leftBufPtr = null; }
+        if (_rightBufPtr && _fluidModule) { try { _fluidModule._free(_rightBufPtr); } catch (e) {} _rightBufPtr = null; }
+        if (_synthPtr && _fluidModule) { try { _fluidModule._delete_fluid_synth(_synthPtr); } catch (e) {} _synthPtr = null; }
+        if (_settingsPtr && _fluidModule) { try { _fluidModule._delete_fluid_settings(_settingsPtr); } catch (e) {} _settingsPtr = null; }
+        _fluidModule = null;
+        _initialized = false;
+    }
+
     window.SonicSF = SonicSF;
 })();

app/static/js/services/soundfontStorage.js

@@ -0,0 +1,56 @@
+(function () {
+    'use strict';
+
+    class SoundFontStorage {
+        constructor() {
+            this.dbName = "DAW_SoundFont_Cache";
+            this.storeName = "sf3_buffers";
+        }
+
+        async openDB() {
+            return new Promise((resolve, reject) => {
+                const request = indexedDB.open(this.dbName, 1);
+                request.onupgradeneeded = (e) => {
+                    const db = e.target.result;
+                    if (!db.objectStoreNames.contains(this.storeName)) {
+                        db.createObjectStore(this.storeName);
+                    }
+                };
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            });
+        }
+
+        async getBuffer(sfId) {
+            try {
+                const db = await this.openDB();
+                return await new Promise((resolve) => {
+                    const tx = db.transaction(this.storeName, "readonly");
+                    const store = tx.objectStore(this.storeName);
+                    const req = store.get(sfId);
+                    req.onsuccess = () => resolve(req.result || null);
+                    req.onerror = () => resolve(null);
+                });
+            } catch (e) {
+                return null;
+            }
+        }
+
+        async saveBuffer(sfId, arrayBuffer) {
+            try {
+                const db = await this.openDB();
+                return await new Promise((resolve, reject) => {
+                    const tx = db.transaction(this.storeName, "readwrite");
+                    const store = tx.objectStore(this.storeName);
+                    const req = store.put(arrayBuffer, sfId);
+                    req.onsuccess = () => resolve(true);
+                    req.onerror = () => reject(req.error);
+                });
+            } catch (e) {
+                return false;
+            }
+        }
+    }
+
+    window.SonicSFStorage = new SoundFontStorage();
+})();

app/static/js/worklets/fluidsynth-bridge.js

@@ -0,0 +1,45 @@
+class FluidSynthBridge extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.leftQ = [];
+    this.rightQ = [];
+    this.called = 0;
+    this.port.onmessage = (e) => {
+      const d = e.data;
+      if (d.type === 'PCM') {
+        this.leftQ.push(d.L);
+        this.rightQ.push(d.R);
+      }
+    };
+  }
+
+  process(inputs, outputs) {
+    const out = outputs[0];
+    if (!out) return true;
+    this.called++;
+    const len = out[0].length;
+    const qL = this.leftQ;
+    const qR = this.rightQ;
+    let fi = 0;
+    let si = 0;
+    for (let i = 0; i < len; i++) {
+      if (fi >= qL.length) { out[0][i] = 0; out[1][i] = 0; continue; }
+      out[0][i] = qL[fi][si];
+      out[1][i] = qR[fi][si];
+      si++;
+      if (si >= qL[fi].length) { fi++; si = 0; }
+    }
+    if (fi > 0) { this.leftQ.splice(0, fi); this.rightQ.splice(0, fi); }
+    if (this.called % 50 === 0) {
+      var pk = 0;
+      for (var j = 0; j < len; j++) {
+        var v = out[0][j] > 0 ? out[0][j] : -out[0][j];
+        if (v > pk) pk = v;
+      }
+      if (pk > 0) console.log('[FluidSynth:bridge] process #' + this.called + ' peak:' + pk.toFixed(6) + ' q:' + qL.length);
+    }
+    return true;
+  }
+}
+
+registerProcessor('fluidsynth-bridge', FluidSynthBridge);

app/templates/index.html

@@ -10,14 +10,16 @@
     <script src="https://unpkg.com/lucide@latest"></script>
     <script src="https://unpkg.com/react@18.3.1/umd/react.production.min.js"></script>
     <script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js"></script>
-    <script src="/static/js/services/api.js?v=202607232105"></script>
-    <script src="/static/js/services/audioEngine.js?v=202607232105"></script>
-    <script src="/static/js/services/storage.js?v=202607232105"></script>
-    <script src="/static/js/services/soundfontPlayer.js?v=202607232105"></script>
-    <script src="/static/js/services/aiGateway.js?v=202607232105"></script>
-    <script src="/static/js/services/dawCommandDispatcher.js?v=202607232105"></script>
-    <script src="/static/js/app.precompiled.js?v=202607232105" defer></script>
-    <link rel="stylesheet" href="/static/css/styles.css?v=202607232105">
+    <script src="/static/js/services/fluidsynthLoader.js?v=202607271245"></script>
+    <script src="/static/js/services/api.js?v=202607271016"></script>
+    <script src="/static/js/services/audioEngine.js?v=202607271016"></script>
+    <script src="/static/js/services/storage.js?v=202607271016"></script>
+    <script src="/static/js/services/soundfontStorage.js?v=202607271016"></script>
+    <script src="/static/js/services/soundfontPlayer.js?v=202607271245"></script>
+    <script src="/static/js/services/aiGateway.js?v=202607271016"></script>
+    <script src="/static/js/services/dawCommandDispatcher.js?v=202607271016"></script>
+    <script src="/static/js/app.precompiled.js?v=202607271245" defer></script>
+    <link rel="stylesheet" href="/static/css/styles.css?v=202607271016">
     <style>
         :root {
             --right-sidebar-width: 320px;

docker-compose.yml

@@ -10,6 +10,9 @@ services:
       - "8000:8000"
     volumes:
       - .:/app
+      - /home/locpham/daw_assets/vst3:/opt/daw_engine/vst3
+      - /home/locpham/daw_assets/soundfonts:/opt/daw_engine/soundfonts
+      - /home/locpham/daw_assets/pianobook:/opt/daw_engine/samples/pianobook
     environment:
       - REDIS_URL=redis://redis:6379/0
       - CELERY_BROKER_URL=redis://redis:6379/0
@@ -22,6 +25,9 @@ services:
     command: celery -A app.tasks.worker.celery_app worker --loglevel=info
     volumes:
       - .:/app
+      - /home/locpham/daw_assets/vst3:/opt/daw_engine/vst3
+      - /home/locpham/daw_assets/soundfonts:/opt/daw_engine/soundfonts
+      - /home/locpham/daw_assets/pianobook:/opt/daw_engine/samples/pianobook
     environment:
       - REDIS_URL=redis://redis:6379/0
       - CELERY_BROKER_URL=redis://redis:6379/0
@@ -34,6 +40,9 @@ services:
     command: celery -A app.tasks.worker.celery_app beat --loglevel=info
     volumes:
       - .:/app
+      - /home/locpham/daw_assets/vst3:/opt/daw_engine/vst3
+      - /home/locpham/daw_assets/soundfonts:/opt/daw_engine/soundfonts
+      - /home/locpham/daw_assets/pianobook:/opt/daw_engine/samples/pianobook
     environment:
       - REDIS_URL=redis://redis:6379/0
       - CELERY_BROKER_URL=redis://redis:6379/0

md/36_USE_VST3.md

@@ -0,0 +1,128 @@
+# OPERATION GUIDE & AUDIO PLAYBACK WORKFLOW FOR MIDI TRACKS (SOUNDFONT / VST3)
+
+This document describes in detail the user interface interaction workflow when using the Synth button and explains the underlying technical architecture required for MIDI Notes on a Track to output audio via a selected SoundFont or VST3 Plugin.
+
+---
+
+## 1. User Interface Workflow Description
+
+### Activating the Instrument Selection Menu
+
+* On the Track Control Panel (the left-side pane of Track 01), the user clicks the **🎵 Synth: BAN-DI** button (or the orange Synth button below it).
+* A dropdown selection menu appears directly underneath the button.
+
+### Instrument Menu Layout
+
+* **None (Default Synth):** Uses the application's default synthesizer (a simple Oscillator Synth).
+* **SOUNDFONTS:** Displays a list of SoundFont (`.sf2`) soundbanks loaded into the system (e.g., `SoundFont_DSK_Asia`, `SoundFont_SGM_v2`, `weedsgm3`).
+* **VST INSTRUMENTS:** Displays a list of native 64-bit Linux VST3 Plugins (e.g., `Vital`, `DecentSampler`, `libSurge XT`).
+
+### Selection & State Update Operations
+
+* The user clicks to select an instrument (e.g., selecting `SoundFont_DSK_Asia` or `Vital`).
+* The menu closes, and the button label updates to reflect the chosen instrument (e.g., **🎵 DSK_Asia** or **🎵 Vital**).
+* The instrument configuration payload is directly assigned to the Track State object (`session.tracks[0].synth_engine`).
+
+---
+
+## 2. Technical Execution Flow for MIDI Note Audio Output (SoundFont / VST3)
+
+To ensure that the purple MIDI note bars on the Timeline or Piano Roll play back audio accurately using the chosen instrument, the system processes tasks across two primary workflows:
+
+```text
+                                  +------------------------------------+
+                                  | User selects SoundFont / VST3      |
+                                  +-----------------+------------------+
+                                                    |
+                         +--------------------------+--------------------------+
+                         |                                                     |
+                         v                                                     v
+          [ 1. Real-time Client Preview ]                        [ 2. Server-side Offline Export ]
+          (Audio Playback in Browser)                             (High-Quality WAV Rendering)
+                         |                                                     |
+    +--------------------+--------------------+                   +------------+------------+
+    |                                         |                   |                         |
+    v                                         v                   v                         v
+(If SoundFont)                          (If VST3)           (If SoundFont)            (If VST3)
+FluidSynth Wasm /                       Load Wasm Module /  PyFluidSynth C-API        Python Pedalboard
+SoundfontPlayer.js                      AudioWorklet Synth  Dispatches Bank/Program   Loads .vst3 binary
+Dispatches programChange                Preview Synth       Renders Audio Buffer      Renders PCM Buffer
+          |                                   |                   |                         |
+          +-----------------+-----------------+                   +------------+------------+
+                            |                                                  |
+                            v                                                  v
+                 AudioContext Destination                            Audio Export Output File
+                 (User Speakers)                                     (Downloaded WAV File)
+
+```
+
+### A. Real-time Client Playback (Browser Audio Preview)
+
+When the user clicks the Play button or clicks a key on the Piano Roll:
+
+1. **Audio Routing Update:**
+* The client reads the instrument parameters from `track.synth_engine`.
+* **If SoundFont (`.sf2`) is selected:** The client dispatches `controllerChange(channel, 0, bank)` and `programChange(channel, program)` configuration calls to the `soundfontPlayer.js` module (running FluidSynth WebAssembly).
+* **If VST3 Plugin (`Vital`, `DecentSampler`, etc.) is selected:** Because browsers cannot natively run Linux `.vst3`/`.so` binary executables directly, the client uses an equivalent WebAssembly Synth or Preview Synth to output real-time audio with $0\text{ ms}$ latency.
+
+
+2. **Note Scheduling:**
+* The Transport driver (`PrecisionAudioScheduler`) scans for MIDI notes located within the moving Playhead range.
+* Each MIDI note includes: `pitch` (0–127), `start_beat` (start position), `duration_beats` (length), and `velocity` (keypress intensity 0.0–1.0).
+* The scheduler converts beat timing to absolute time in seconds (`exactAudioTime`) and dispatches audio events:
+* `noteOn(pitch, velocity, exactAudioTime)`
+* `noteOff(pitch, exactAudioTime + durationSec)`
+
+
+* Audio signals generated by the WebAssembly Engine travel through `Track Gain Node` $\rightarrow$ `Track Pan Node` $\rightarrow$ `Master Bus` $\rightarrow$ `AudioContext.destination` (User Speakers).
+
+
+
+### B. Server-side Offline Render (High-Quality WAV Export)
+
+When the user exports a track (Bounce Track / Export WAV), the Python Backend on the server receives the project's JSON payload:
+
+1. **Reading Track Instrument Metadata:**
+```json
+{
+  "track_id": "track_01",
+  "synth_engine": {
+    "type": "VST3",
+    "plugin_id": "Vital",
+    "soundfont_bank": 0,
+    "soundfont_program": 0
+  }
+}
+
+```
+
+
+2. **Rendering SoundFont (`.sf2`) Instruments:**
+* `render_engine.py` initializes a FluidSynth instance.
+* Calls `fl.program_select(channel, sf_id, bank, program)`.
+* Feeds the list of MIDI notes directly to FluidSynth to render an Audio Buffer.
+
+
+3. **Rendering VST3 (`.vst3`) Instruments:**
+* `vst_engine.py` invokes `pedalboard.VST3Plugin("/opt/daw_engine/vst3/Vital.vst3")`.
+* If DecentSampler is selected, it loads the corresponding Pianobook sample preset file (`.dspreset`).
+* Converts all MIDI Notes into an array of `pedalboard.Message` events:
+* Inserts `control_change` (Bank Select) and `program_change` events at timestamp $0.0\text{ s}$.
+* Inserts `note_on` and `note_off` events matching the pitch and duration parameters of each note.
+
+
+* Feeds the MIDI message stream into the VST3 instance to generate a high-fidelity Float32 PCM audio stream.
+* Mixes down the Track PCM Audio Buffers into the Master Mix and creates the final `.wav` output file.
+
+
+
+---
+
+## 3. Instrument Selection Checklist
+
+To ensure that selecting an instrument via the Synth button produces audio output successfully:
+
+* [ ] **Track is Unmuted:** Verify that the Mute button `[M]` is not active (orange/red) and that the Solo button `[S]` on other tracks is not muting the current track.
+* [ ] **MIDI Notes in Valid Key Range:** Some instruments (such as Bass or Horns) operate within constrained pitch boundaries (e.g., C1 to C5). Ensure the notes drawn on the Piano Roll fall within the playable range of the selected SoundFont or VST3 instrument.
+* [ ] **VST3 / SoundFont Files Ready on Server:** Confirm that the `.vst3` binary files are placed inside `/opt/daw_engine/vst3/` and `.sf2` files are present in `/opt/daw_engine/soundfonts/`.
+* [ ] **Appropriate Volume / Gain Settings:** Verify that the Track 01 Volume slider is configured to $0\text{ dB}$ to avoid signal clipping or silent playback.

md/37_FIXVST3_SUGGEST.md

@@ -0,0 +1,86 @@
+Nguyên nhân xuất hiện thông báo lỗi từ SpessaSynth Core:
+`basic_synthesizer_core.ts:169 No preset found for 0:0:0! Did you forget to add a sound bank?`
+
+Thông số `0:0:0` trong thông báo đại diện cho `Bank MSB : Bank LSB : Program Number` (cấu hình mặc định ban đầu của kênh MIDI). Lỗi này xảy ra do **3 nguyên nhân chính** sau:
+
+---
+
+### 1. Phân tích nguyên nhân kỹ thuật
+
+1. **Chưa gửi lệnh `programChange` & `controllerChange` sang SpessaSynth khi chọn "Pipa"**:
+* Khi chọn nhạc cụ "Pipa" trên UI, ứng dụng mới chỉ cập nhật giao diện mà **chưa kích hoạt lệnh đổi tiếng** (`synthInstance.programChange(channel, program)`) sang kênh MIDI tương ứng của SpessaSynth.
+* Khi gõ phím trên `SE49` (nhận dữ liệu Raw MIDI `[144, 65, 78]`), SpessaSynth vẫn truy xuất bộ tiếng ở vị trí mặc định là `Bank 0 : Program 0` (thường là Grand Piano theo chuẩn General MIDI).
+* Trong SoundFont `DSK_Asian_DreamZ`, vị trí `0:0:0` không tồn tại hoặc không chứa thông tin nốt, khiến SpessaSynth thông báo không tìm thấy preset.
+
+
+2. **Sai chỉ số Bank / Program của nhạc cụ "Pipa"**:
+* Tệp SoundFont `DSK_Asian_DreamZ` là bộ tiếng tùy chỉnh (Non-General MIDI). 8 nhạc cụ bên trong (*Pipa, Pipa Tremolo, Luan, Guzhen, Erhu, Koto, Ban Di, Percussion*) được đánh số `Program` riêng biệt.
+* Nếu UI gửi `program = 0` nhưng thực tế trong file SoundFont, tiếng Pipa nằm ở `program = 1` hoặc `bank = 1`, SpessaSynth sẽ không tìm thấy preset tương ứng.
+
+
+3. **Lỗi Header/Mapping khi convert từ `.sf2` sang `.sf3**`:
+* Một số công cụ nén (như `mscore` CLI) khi convert các SoundFont tùy chỉnh có cấu trúc phi chuẩn có thể làm mất hoặc biến đổi bảng thông tin Preset Header.
+
+
+
+---
+
+### 2. Các bước khắc phục
+
+#### **Bước 1: Gọi `programChange` & `controllerChange` ngay khi chọn nhạc cụ trên UI**
+
+Đảm bảo khi người dùng chọn nhạc cụ trên giao diện, hàm chọn Bank/Program được kích hoạt trên kênh MIDI phát tiếng:
+
+```javascript
+// Khi người dùng chọn "Pipa" trên Dropdown Synth UI
+async function onSelectTrackInstrument(trackChannel, sfId, bank, program) {
+    // 1. Nạp file .sf3 vào SpessaSynth (nếu chưa nạp)
+    await soundFontPlayerInstance.loadSoundFont(sfId);
+
+    // 2. BẮT BUỘC: Gửi lệnh đổi Bank (CC 0) và Program Change sang SpessaSynth
+    if (soundFontPlayerInstance.synthInstance) {
+        soundFontPlayerInstance.synthInstance.controllerChange(trackChannel, 0, bank);
+        soundFontPlayerInstance.synthInstance.programChange(trackChannel, program);
+        console.log(`[SonicSF] Switched Channel ${trackChannel} -> Bank: ${bank}, Program: ${program}`);
+    }
+}
+
+```
+
+#### **Bước 2: Kiểm tra chính xác chỉ số Bank & Program của Pipa từ Catalog API**
+
+Sử dụng API `GET /api/v1/plugins/soundfonts/catalog` (từ mô-đun `SoundFontInspector` đã xây dựng) để tra cứu vị trí chính xác của "Pipa":
+
+```json
+"dsk_asian_dreamz": {
+  "soundfont_id": "dsk_asian_dreamz",
+  "instruments": [
+    { "bank": 0, "program": 0, "name": "Pipa" },
+    { "bank": 0, "program": 1, "name": "Pipa Tremolo" },
+    { "bank": 0, "program": 6, "name": "Ban Di" }
+  ]
+}
+
+```
+
+*Lưu ý:* Nếu kết quả trả về tiếng Pipa nằm ở `program: 1` hoặc `bank: 1`, hãy truyền đúng thông số này vào hàm `programChange`.
+
+#### **Bước 3: Kiểm tra danh sách Presets mà SpessaSynth đọc được từ file `.sf3**`
+
+Để đảm bảo quá trình convert `.sf3` không làm hỏng dữ liệu Preset Header, bạn hãy log danh sách preset sau khi nạp tệp:
+
+```javascript
+// Thêm log kiểm tra sau khi addSoundFont vào SpessaSynth
+try {
+    await this.synthInstance.soundFontManager.addSoundFont(buffer);
+    
+    // In danh sách các preset đọc được ra console để kiểm tra
+    const loadedSF = this.synthInstance.soundFontManager.soundFonts[0];
+    console.log("[SonicSF] Loaded Presets in SF3:", loadedSF.presets);
+} catch (e) {
+    console.error("[SonicSF] Error parsing SF3:", e);
+}
+
+```
+
+* Nếu `loadedSF.presets` rỗng (`[]`), file `.sf3` đã bị hỏng khi nén. Bạn hãy thử nạp lại file `.sf2` gốc chưa nén để đối chiếu.

md/37_SF_CONVERT.md

@@ -0,0 +1,322 @@
+# TECHNICAL SPECIFICATION: CLIENT SOUNDFONT OPTIMIZATION USING SF3 AND SPESSASYNTH
+
+This document details a two-step technical workflow to upgrade the real-time client audio playback experience:
+
+1. **Server Asset Conversion:** Converts original `.sf2` files into compressed `.sf3` (Ogg Vorbis) format, reducing file size from $30 - 150\text{ MB}$ down to just $3 - 6\text{ MB}$ ($\sim 85-90\%$ compression).
+2. **Client Engine Upgrade:** Replaces the oscillator emulation logic inside `soundfontPlayer.js` with the SpessaSynth library (Web Audio API / AudioWorklet Engine), achieving $100\%$ authentic audio rendering relative to the server exporter with initial load times of only $1 - 2\text{ seconds}$.
+
+---
+
+## STEP 1: AUTOMATED SF2 TO SF3 ASSET CONVERSION ON SERVER
+
+### 1.1 Technical Principles of the `.sf3` Format
+
+* `.sf2` files store raw uncompressed PCM Float/Int audio samples (Raw Uncompressed Audio).
+* `.sf3` files preserve the complete Header, Preset, and Instrument Mapping structure of SF2, but compress raw WAV sample streams using the Ogg Vorbis compression algorithm.
+* Human ears cannot distinguish quality differences between `.sf2` and `.sf3` playback, but the reduced footprint ensures exceptionally fast browser downloads.
+
+### 1.2 Installing Conversion Utilities in Server Docker (`Dockerfile`)
+
+Append `mscore` (MuseScore CLI) or `sf2pack` packages to the `Dockerfile`:
+
+```dockerfile
+# Dockerfile
+RUN apt-get update && apt-get install -y \
+    mscore \
+    vorbis-tools \
+    && rm -rf /var/lib/apt/lists/*
+
+```
+
+### 1.3 Python Automated SoundFont Converter Module (`app/core/soundfont_converter.py`)
+
+Creates a Python module to automatically scan `.sf2` files within system/upload directories and generate parallel `.sf3` converted files:
+
+```python
+import os
+import subprocess
+import logging
+
+logger = logging.getLogger(__name__)
+
+class SoundFontConverter:
+    def __init__(self, target_dirs=None):
+        if target_dirs is None:
+            self.target_dirs = [
+                "/opt/daw_engine/soundfonts",
+                "app/storage/uploads/soundfonts"
+            ]
+        else:
+            self.target_dirs = target_dirs
+
+    def convert_sf2_to_sf3(self, sf2_path: str) -> str:
+        """
+        Converts a single .sf2 file to .sf3 using MuseScore CLI.
+        Returns the path to the converted .sf3 file.
+        """
+        if not os.path.exists(sf2_path):
+            raise FileNotFoundError(f"Source SF2 file not found: {sf2_path}")
+
+        sf3_path = os.path.splitext(sf2_path)[0] + ".sf3"
+
+        # Check if already converted and up-to-date
+        if os.path.exists(sf3_path) and os.path.getmtime(sf3_path) >= os.path.getmtime(sf2_path):
+            return sf3_path
+
+        try:
+            logger.info(f"Converting '{sf2_path}' -> '{sf3_path}'...")
+            # Command: mscore -o output.sf3 input.sf2
+            cmd = ["mscore", "-o", sf3_path, sf2_path]
+            result = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+
+            if result.returncode == 0 and os.path.exists(sf3_path):
+                logger.info(f"Successfully created SF3 asset: {sf3_path} ({os.path.getsize(sf3_path) / (1024*1024):.2f} MB)")
+                return sf3_path
+            else:
+                logger.error(f"SF2 to SF3 conversion failed: {result.stderr}")
+                return sf2_path # Fallback to original SF2
+        except Exception as e:
+            logger.error(f"Error executing SF2 conversion: {str(e)}")
+            return sf2_path
+
+    def batch_convert_all(self):
+        """
+        Scans all target directories and converts any missing .sf3 files.
+        """
+        for sdir in self.target_dirs:
+            if not os.path.exists(sdir):
+                continue
+            for root, _, files in os.walk(sdir):
+                for file in files:
+                    if file.lower().endswith('.sf2'):
+                        full_sf2_path = os.path.join(root, file)
+                        self.convert_sf2_to_sf3(full_sf2_path)
+
+```
+
+### 1.4 API Endpoint Serving `.sf3` Files to Clients (`app/api/v1/plugins.py`)
+
+Provides a static download route serving optimized `.sf3` assets:
+
+```python
+@router.get("/soundfonts/download/{sf_id}")
+async def download_soundfont_asset(sf_id: str):
+    """
+    Returns the optimized .sf3 file if available, otherwise falls back to .sf2.
+    """
+    sf3_path = f"/opt/daw_engine/soundfonts/{sf_id}.sf3"
+    sf2_path = f"/opt/daw_engine/soundfonts/{sf_id}.sf2"
+
+    if os.path.exists(sf3_path):
+        return FileResponse(sf3_path, media_type="application/octet-stream", filename=f"{sf_id}.sf3")
+    elif os.path.exists(sf2_path):
+        return FileResponse(sf2_path, media_type="application/octet-stream", filename=f"{sf_id}.sf2")
+    else:
+        raise HTTPException(status_code=404, detail="SoundFont asset not found")
+
+```
+
+---
+
+## STEP 2: UPGRADING CLIENT PLAYER USING SPESSASYNTH
+
+SpessaSynth (`spessasynth_lib`) is a next-generation JavaScript SoundFont Synthesizer written entirely using the Web Audio API & AudioWorklet. It supports direct loading of `.sf3` files without requiring complex C/Wasm compilation wrappers.
+
+### 2.1 Integrating the SpessaSynth Library into Frontend
+
+Add the npm package or embed the ES Module script directly inside `index.html`:
+
+```html
+<!-- index.html -->
+<script type="module">
+  import { Synthesizer } from 'https://cdn.jsdelivr.net/npm/spessasynth_lib@latest/dist/spessasynth_lib.js';
+  window.SpessaSynthClass = Synthesizer;
+</script>
+
+```
+
+### 2.2 Client Storage Optimization (`IndexedDB`)
+
+Caches downloaded `.sf3` files inside `IndexedDB` so that upon reopening the browser, the application loads audio buffers instantly in $0\text{ms}$ without re-fetching from the server.
+
+```javascript
+// app/static/js/services/soundfontStorage.js
+class SoundFontStorage {
+  constructor() {
+    this.dbName = "DAW_SoundFont_Cache";
+    this.storeName = "sf3_buffers";
+  }
+
+  async openDB() {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, 1);
+      request.onupgradeneeded = (e) => {
+        const db = e.target.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName);
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async getBuffer(sfId) {
+    const db = await this.openDB();
+    return new Promise((resolve) => {
+      const tx = db.transaction(this.storeName, "readonly");
+      const store = tx.objectStore(this.storeName);
+      const req = store.get(sfId);
+      req.onsuccess = () => resolve(req.result || null);
+      req.onerror = () => resolve(null);
+    });
+  }
+
+  async saveBuffer(sfId, arrayBuffer) {
+    const db = await this.openDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, "readwrite");
+      const store = tx.objectStore(this.storeName);
+      const req = store.put(arrayBuffer, sfId);
+      req.onsuccess = () => resolve(true);
+      req.onerror = () => reject(req.error);
+    });
+  }
+}
+
+export const sfStorage = new SoundFontStorage();
+
+```
+
+### 2.3 Comprehensive Upgrade of `soundfontPlayer.js`
+
+Replaces oscillator emulation loops with the SpessaSynth Engine:
+
+```javascript
+// app/static/js/services/soundfontPlayer.js
+import { sfStorage } from './soundfontStorage.js';
+
+class RealSoundFontPlayer {
+  constructor() {
+    this.audioCtx = null;
+    this.synthInstance = null;
+    this.currentSfId = null;
+    this.isInitialized = false;
+  }
+
+  async init(audioContext) {
+    if (this.isInitialized) return;
+    this.audioCtx = audioContext;
+
+    if (window.SpessaSynthClass) {
+      // Initialize SpessaSynth Synthesizer routed to Web Audio Destination
+      this.synthInstance = new window.SpessaSynthClass(this.audioCtx.destination);
+      this.isInitialized = true;
+      console.log("[SonicSF] SpessaSynth Engine Initialized successfully.");
+    } else {
+      console.warn("[SonicSF] SpessaSynth library not loaded. Falling back to basic audio.");
+    }
+  }
+
+  /**
+   * Loads .sf3 file from IndexedDB Cache or Server API
+   */
+  async loadSoundFont(sfId = "generaluser_gs") {
+    if (!this.isInitialized) return;
+    if (this.currentSfId === sfId) return;
+
+    console.log(`[SonicSF] Loading SoundFont asset: ${sfId}...`);
+
+    // 1. Try fetching from IndexedDB Cache
+    let buffer = await sfStorage.getBuffer(sfId);
+
+    if (!buffer) {
+      // 2. If missing, download .sf3 asset from Server (~4MB footprint)
+      try {
+        const response = await fetch(`/api/v1/plugins/soundfonts/download/${sfId}`);
+        if (!response.ok) throw new Error("Network download failed");
+        buffer = await response.arrayBuffer();
+
+        // Save to IndexedDB for instant future loads
+        await sfStorage.saveBuffer(sfId, buffer);
+      } catch (err) {
+        console.error(`[SonicSF] Failed to load SoundFont '${sfId}':`, err);
+        return;
+      }
+    }
+
+    // 3. Load .sf3 ArrayBuffer into SpessaSynth Engine
+    try {
+      await this.synthInstance.soundFontManager.addSoundFont(buffer);
+      this.currentSfId = sfId;
+      console.log(`[SonicSF] SoundFont '${sfId}' loaded into Wasm/JS memory.`);
+    } catch (e) {
+      console.error("[SonicSF] Error parsing SF3 buffer in SpessaSynth:", e);
+    }
+  }
+
+  /**
+   * Configures MIDI Channel, Bank, Program
+   */
+  applyAITrackInstrument(channel, bank, program) {
+    if (!this.synthInstance) return;
+    // Bank Select (CC 0)
+    this.synthInstance.controllerChange(channel, 0, bank);
+    // Program Change
+    this.synthInstance.programChange(channel, program);
+  }
+
+  /**
+   * Plays a MIDI note in real time with 100% authentic instrument sound
+   */
+  playNote(pitch, velocity = 0.8, durationSec = 1.0, channel = 0) {
+    if (!this.synthInstance) return;
+
+    const midiPitch = Math.min(127, Math.max(0, pitch));
+    const midiVelocity = Math.floor(velocity * 127);
+
+    // Note On
+    this.synthInstance.noteOn(channel, midiPitch, midiVelocity);
+
+    // Note Off scheduled by duration
+    setTimeout(() => {
+      this.synthInstance.noteOff(channel, midiPitch);
+    }, durationSec * 1000);
+  }
+}
+
+export const soundFontPlayerInstance = new RealSoundFontPlayer();
+
+```
+
+---
+
+## UI INTEGRATION WORKFLOW (`app.jsx`)
+
+1. **Application Startup:**
+* When the user clicks on the web page or triggers Transport Play, call `soundFontPlayerInstance.init(audioCtx)` and trigger a background fetch for the default General SoundFont (`generaluser_gs.sf3`).
+
+
+2. **When User Selects Instrument via Synth Button:**
+* Read `sf_id` from the selected instrument object.
+* Call `await soundFontPlayerInstance.loadSoundFont(sf_id)`.
+* Call `soundFontPlayerInstance.applyAITrackInstrument(channel, bank, program)`.
+
+
+3. **When Playing Piano Roll / Timeline:**
+* Every emitted MIDI note invokes `soundFontPlayerInstance.playNote(pitch, velocity, durationSec, channel)`.
+* Audio signals pass through Envelopes, Modulators, and Standard General MIDI Sample Mapping via SpessaSynth $\rightarrow$ outputs $100\%$ authentic instrument audio matching the server WAV export engine.
+
+
+
+---
+
+## POST-OPTIMIZATION PERFORMANCE COMPARISON
+
+| Metric | Before Optimization (SF2 + Oscillator) | After Optimization (SF3 + SpessaSynth) |
+| --- | --- | --- |
+| **Asset Download Size** | $35\text{ MB} - 140\text{ MB}$ (Extremely Heavy) | 🟢 $3.5\text{ MB} - 5.5\text{ MB}$ (Ultra Light) |
+| **Initial Load Time** | $10 - 25\text{ seconds}$ | ⚡ $1 - 2\text{ seconds}$ |
+| **Subsequent Load Time** | $10 - 25\text{ seconds}$ | ⚡ $0\text{ seconds}$ (Retrieved from IndexedDB Cache) |
+| **Preview Fidelity** | 🔴 Crude Emulated Waveform (Oscillator) | 🟢 $100\%$ Authentic SoundFont Rendering |
+| **Keypress Latency** | $0\text{ms}$ | ⚡ $0\text{ms}$ (Runs on AudioWorklet) |

md/38_FLOWCLIENT.md

@@ -0,0 +1,144 @@
+# CLIENT-SIDE EXECUTION FLOW (SF3 + SPESSASYNTH + INDEXEDDB)
+
+This document describes the step-by-step processing chain that takes place inside the Client Browser, from launching the Web DAW application, downloading and buffering `.sf3` instrument files, and setting up MIDI channels, to outputting real-time audio.
+
+---
+
+## 1. SEQUENCE DIAGRAM
+
+```text
+[ USER / UI ]        [ APP / CLIENT ]        [ INDEXEDDB ]        [ SERVER API ]      [ SPESSASYNTH ENGINE ]
+      |                     |                      |                    |                       |
+1. Open Web Page ---------> | Initial AudioCtx     |                    |                       |
+      |                     | Init SpessaSynth -----------------------------------------------> | Connect Destination
+      |                     | Fetch Catalog --------------------------->| Get /catalog          |
+      |                     |                      |                    |                       |
+2. Select Instrument -----> | Read (sf_id, bank, prog)                  |                       |
+   (e.g., Pipa)             | Query SF3 Buffer --->| Check Key (sf_id)  |                       |
+      |                     |                      | -- (Miss) -------->| Fetch /download/sf_id |
+      |                     |                      |                    | Return .sf3 (~4MB)    |
+      |                     | <--------------------| Save ArrayBuffer --|                       |
+      |                     | Load SF3 Memory ------------------------------------------------> | addSoundFont(buffer)
+      |                     |                      |                    |                       |
+3. Channel Router --------> | Switch Bank/Program -------------------------------------------> | controllerChange(ch, 0, bank)
+      |                     |                      |                    |                       | programChange(ch, prog)
+      |                     |                      |                    |                       |
+4. Trigger MIDI Key ------> | Raw MIDI Event       |                    |                       |
+   (or Timeline Play)       | (noteOn: pitch, vel) -------------------------------------------> | noteOn(ch, pitch, vel)
+      |                     |                      |                    |                       | AudioWorklet Synthesis
+      |                     | <------------------------------------------------------------------ | Audio Out (User Speakers)
+
+```
+
+---
+
+## 2. DETAILED PROCESSING PHASES
+
+### PHASE 1: BOOTSTRAPPING & ENGINE INIT
+
+* **Web Audio Context Initialization:** Upon the user's first interaction with the web page (Mouse Click/Keypress), the application initializes the `AudioContext`.
+* **SpessaSynth Synthesizer Initialization:** The `soundfontPlayer.js` module instantiates `SpessaSynthClass` and connects its output directly to `audioCtx.destination`:
+```javascript
+this.synthInstance = new window.SpessaSynthClass(this.audioCtx.destination);
+
+```
+
+
+* **Instrument Catalog Load (Catalog Context):** The Frontend dispatches a `GET /api/v1/plugins/soundfonts/catalog` request to load the `condensed_catalog`, which contains lookup tables for `sf_id`, `bank`, and `program`.
+
+---
+
+### PHASE 2: `.SF3` ASSET LOADING & CACHING
+
+Triggered when a user selects an instrument via the Synth UI button (or when the AI Copilot spawns a new Track with a designated instrument, e.g., `dsk_asian_dreamz`):
+
+* **Query Browser Cache (IndexedDB):** The Client calls `sfStorage.getBuffer(sfId)` to search for the `.sf3` file's `ArrayBuffer` inside the `DAW_SoundFont_Cache` database.
+* **Handling Cache Hit vs Cache Miss:**
+* **Cache Hit ($0\text{ms}$):** Retrieves the `ArrayBuffer` directly from the browser's RAM/Storage.
+* **Cache Miss:**
+1. Sends a `GET /api/v1/plugins/soundfonts/download/{sf_id}` request to the Server.
+2. Downloads the compressed, optimized `.sf3` asset (ultra-lightweight size $\sim 3.5 - 5.5\text{ MB}$).
+3. Invokes `sfStorage.saveBuffer(sfId, arrayBuffer)` to store it inside IndexedDB for subsequent visits.
+
+
+
+
+* **Load Data into SpessaSynth Wasm/JS Memory:** Passes the `ArrayBuffer` to SpessaSynth Engine's `SoundFontManager`:
+```javascript
+await this.synthInstance.soundFontManager.addSoundFont(buffer);
+
+```
+
+
+
+---
+
+### PHASE 3: BANK/PROGRAM ROUTING & MIDI CHANNEL SETUP
+
+This is the most critical phase to resolve `No preset found for 0:0:0` errors.
+
+* **MIDI Channel Assignment:**
+* **Melodic Instruments (Piano, Pipa, Strings, Brass, etc.):** Allocated to Channels 0 through 8.
+* **Percussion / Drum Kits (Bank 128):** Mandatory allocation to Channel 9 (GM Standard Channel 10).
+
+
+* **Dispatch Bank Select & Program Change to SpessaSynth Engine:** Prior to scheduling any note events, the Client triggers two simultaneous control events:
+```javascript
+// 1. Select Bank (Control Change 0)
+this.synthInstance.controllerChange(channel, 0, bank);
+
+// 2. Select Program (Program Change)
+this.synthInstance.programChange(channel, program);
+
+```
+
+
+*Example for Pipa (`dsk_asian_dreamz`):* Calls `controllerChange(0, 0, 0)` and `programChange(0, 0)`. SpessaSynth switches Channel 0's state to the Pipa instrument patch.
+
+---
+
+### PHASE 4: REALTIME SYNTHESIS & AUDIO OUTPUT
+
+Triggered when receiving note-control signals (from a Hardware MIDI Keyboard or Timeline Transport Playback):
+
+* **Scenario A: User plays a Hardware MIDI Keyboard (e.g., Nektar SE49)**
+1. The browser receives a Raw MIDI Event: Web MIDI API captures message `[144, 65, 78]` (`NoteOn`, `Pitch 65`, `Velocity 78`).
+2. **Latency Compensation:** Calculates real-time offsets and issues `NoteOn` to SpessaSynth:
+```javascript
+const midiPitch = pitch;
+const midiVelocity = Math.floor(velocity * 127);
+this.synthInstance.noteOn(channel, midiPitch, midiVelocity);
+
+```
+
+
+3. **Key Release:** Triggers a `NoteOff` event:
+```javascript
+this.synthInstance.noteOff(channel, midiPitch);
+
+```
+
+
+
+
+* **Scenario B: User triggers Play on Timeline / Piano Roll**
+1. **Transport Controller & Scheduler (`PrecisionAudioScheduler`):** Scans for MIDI notes located within the moving Playhead window.
+2. **Note Scheduling:**
+* Converts beat positions to precise audio timing based on BPM tempo (`exactAudioTime`).
+* Dispatches `noteOn(channel, pitch, velocity)` at the exact timestamp $T_{\text{start}}$.
+* Dispatches `noteOff(channel, pitch)` at timestamp $T_{\text{start}} + T_{\text{duration}}$.
+
+
+
+
+* **Audio Worklet Audio Rendering:** SpessaSynth Engine reads Ogg/WAV sample data inside the `.sf3` asset, applies Envelopes (ADSR), Modulators, and Gain Control parameters on the designated Channel, and pushes PCM audio data directly to user speakers with $0\text{ms}$ latency.
+
+---
+
+## 3. 100% RELIABILITY VERIFICATION CHECKLIST
+
+* [ ] `.sf3` files loaded into the browser open without triggering `Corrupted File` errors.
+* [ ] The `sfStorage.getBuffer` function successfully stores and retrieves `ArrayBuffer` data from IndexedDB.
+* [ ] Both `controllerChange(channel, 0, bank)` and `programChange(channel, program)` are invoked immediately upon changing instruments on the UI.
+* [ ] Percussion/Drum instruments are persistently allocated to Channel 9.
+* [ ] Console logs confirm: `[SonicSF] Switched Channel X -> Bank: B, Program: P`.

md/39_SF3_NEW.md

@@ -0,0 +1,300 @@
+# TECHNICAL SPECIFICATION: AUDIO ENGINE MIGRATION FROM SPESSASYNTH TO FLUIDSYNTH WASM
+
+This document details the workflow for migrating the Client-side Audio Engine from SpessaSynth (JavaScript/AudioWorklet) to FluidSynth Wasm (C++ Compiled WebAssembly). This resolves stuck notes issues (e.g., Tremolo/Saxophone presets), ensures $100\%$ SoundFont 2.04 specification compliance, and synchronizes the real-time preview experience with Server-side rendering output.
+
+---
+
+## 1. ARCHITECTURAL COMPARISON & MIGRATION RATIONALE
+
+| CRITERIA | SPESSASYNTH (JS ENGINE) | FLUIDSYNTH WASM (C++ ENGINE) |
+| --- | --- | --- |
+| **Core Nature** | Written entirely in JavaScript / AudioWorklet | Native C++ source code of FluidSynth compiled via Emscripten Wasm |
+| **Loop Mode Processing (Gen 54)** | Prone to unreleased loop bugs upon receiving `noteOff` on Tremolo/Sustain sounds | $100\%$ compliant decoding of mode 3 ("Loop during key press") & Release Envelopes |
+| **Voice Lookup Engine** | Simple `HashMap` `(channel, pitch)` management, prone to Voice ID desynchronization | Precise C++ Voice ID Pointer management matching Reaper / LinuxSampler standards |
+| **Asset Loading** | Loads `ArrayBuffer` directly into JS Memory | Writes `ArrayBuffer` into Virtual File System (Emscripten MEMFS) |
+| **ADSR Stability** | Dependent on JS Worklet Thread Timers | Runs within C-DSP processing loops with sample-accurate precision ($0\text{ms}$ delay) |
+
+---
+
+## 2. NEW INTEGRATION ARCHITECTURE (FLUIDSYNTH WASM ARCHITECTURE)
+
+```text
+[ WEB DAW UI / PIANO ROLL / MIDI KEYBOARD ]
+                    |
+                    v
+    [ soundfontPlayer.js (Singleton) ]
+                    |
+        +-----------+-----------+
+        |                       |
+        v                       v
+[ IndexedDB / Network ]   [ Emscripten MEMFS (Virtual FS) ]
+(Downloads .sf2 / .sf3)    (Writes file: /soundfonts/bank.sf3)
+                                |
+                                v
+                   [ FluidSynth C-Wasm Instance ]
+                   (_fluid_synth_sfload)
+                                |
+                                v
+                   [ AudioWorkletNode (PCM Rendering) ]
+                                |
+                                v
+                   [ Web Audio Destination (Speakers) ]
+
+```
+
+---
+
+## 3. DETAILED CODE IMPLEMENTATION (`soundfontPlayer.js`)
+
+Replace the existing `soundfontPlayer.js` codebase with the following implementation:
+
+```javascript
+// app/static/js/services/soundfontPlayer.js
+import { sfStorage } from './soundfontStorage.js';
+
+class FluidSynthWasmPlayer {
+  constructor() {
+    this.audioCtx = null;
+    this.fluidModule = null;
+    this.synthPtr = null;
+    this.workletNode = null;
+    this.loadedFontsMap = new Map(); // sfId -> sfHandle
+    this.currentSfId = null;
+    this.isInitialized = false;
+  }
+
+  /**
+   * Initializes WebAssembly Module and Audio Context Graph
+   */
+  async init(audioContext) {
+    if (this.isInitialized) return;
+    this.audioCtx = audioContext;
+
+    if (this.audioCtx.state === 'suspended') {
+      await this.audioCtx.resume();
+    }
+
+    console.log("[SonicSF] Initializing FluidSynth Wasm Engine...");
+
+    // 1. Load WebAssembly Module (Fluidsynth Emscripten Wrapper)
+    if (window.createFluidSynthModule) {
+      this.fluidModule = await window.createFluidSynthModule();
+    } else {
+      throw new Error("FluidSynth Wasm library not found. Ensure fluidsynth.js is loaded in index.html.");
+    }
+
+    // 2. Instantiate FluidSynth C++ Settings & Synthesizer
+    const settingsPtr = this.fluidModule._new_fluid_settings();
+    // Set sample rate matching Web AudioContext
+    this.fluidModule._fluid_settings_setnum(settingsPtr, "synth.sample-rate", this.audioCtx.sampleRate);
+    this.synthPtr = this.fluidModule._new_fluid_synth(settingsPtr);
+
+    // 3. Create virtual MEMFS directory to store SoundFont files
+    try {
+      this.fluidModule.FS.mkdir('/soundfonts');
+    } catch (e) {
+      // Ignore if folder already exists
+    }
+
+    // 4. Connect C++ Audio Generator to Web Audio Context via AudioWorklet
+    await this._initAudioWorkletNode();
+
+    this.isInitialized = true;
+    console.log("[SonicSF] FluidSynth Wasm Engine initialized successfully.");
+  }
+
+  /**
+   * Initializes AudioWorkletNode to stream PCM Float32 Buffers to user speakers
+   */
+  async _initAudioWorkletNode() {
+    // Register AudioWorkletProcessor reading directly from C++ Buffer Pointer
+    await this.audioCtx.audioWorklet.addModule('/static/js/worklets/fluidsynth-processor.js');
+    
+    this.workletNode = new AudioWorkletNode(this.audioCtx, 'fluidsynth-processor', {
+      outputChannelCount: [2]
+    });
+
+    // Pass C++ Pointers to Worklet Processor
+    this.workletNode.port.postMessage({
+      type: 'INIT_SYNTH',
+      wasmModule: this.fluidModule,
+      synthPtr: this.synthPtr
+    });
+
+    this.workletNode.connect(this.audioCtx.destination);
+  }
+
+  /**
+   * Loads .sf2 / .sf3 files from Cache or Server into Virtual File System (MEMFS)
+   */
+  async loadSoundFont(sfId) {
+    if (!this.isInitialized) return false;
+    if (this.currentSfId === sfId) return true;
+
+    // Check if already loaded in C++ memory
+    if (this.loadedFontsMap.has(sfId)) {
+      this.currentSfId = sfId;
+      return true;
+    }
+
+    console.log(`[SonicSF] Loading SoundFont asset '${sfId}' into Wasm MEMFS...`);
+
+    // 1. Fetch ArrayBuffer from IndexedDB or Server API
+    let buffer = await sfStorage.getBuffer(sfId);
+    if (!buffer) {
+      const response = await fetch(`/api/v1/plugins/soundfonts/download/${sfId}`);
+      if (!response.ok) {
+        console.error(`[SonicSF] Failed to download SoundFont asset: ${sfId}`);
+        return false;
+      }
+      buffer = await response.arrayBuffer();
+      await sfStorage.saveBuffer(sfId, buffer);
+    }
+
+    // 2. Write ArrayBuffer to Emscripten Virtual File System (MEMFS)
+    const virtualPath = `/soundfonts/${sfId}.sf3`;
+    this.fluidModule.FS.writeFile(virtualPath, new Uint8Array(buffer));
+
+    // 3. Call C function _fluid_synth_sfload to load SoundFont into Engine
+    const sfHandle = this.fluidModule._fluid_synth_sfload(this.synthPtr, virtualPath, 1);
+
+    if (sfHandle === -1) {
+      console.error(`[SonicSF] FluidSynth C++ failed to parse SoundFont file at ${virtualPath}`);
+      return false;
+    }
+
+    this.loadedFontsMap.set(sfId, sfHandle);
+    this.currentSfId = sfId;
+    console.log(`[SonicSF] SoundFont '${sfId}' loaded successfully with Handle ID: ${sfHandle}`);
+    return true;
+  }
+
+  /**
+   * Executes Instrument / Bank / Program Change on MIDI Channel
+   */
+  selectInstrument(channel, bank, program) {
+    if (!this.synthInstanceAvailable()) return;
+
+    // Bank Select (CC 0)
+    this.fluidModule._fluid_synth_bank_select(this.synthPtr, channel, bank);
+    // Program Change
+    this.fluidModule._fluid_synth_program_change(this.synthPtr, channel, program);
+
+    console.log(`[SonicSF] FluidSynth Channel ${channel} -> Bank: ${bank}, Program: ${program}`);
+  }
+
+  /**
+   * Triggers Note On
+   */
+  noteOn(channel, pitch, velocity = 0.8) {
+    if (!this.synthInstanceAvailable()) return;
+
+    const midiPitch = Math.min(127, Math.max(0, parseInt(pitch, 10)));
+    const midiVel = Math.floor(Math.min(1.0, Math.max(0.0, velocity)) * 127);
+
+    // Trigger note via direct C++ call
+    this.fluidModule._fluid_synth_noteon(this.synthPtr, channel, midiPitch, midiVel);
+  }
+
+  /**
+   * Triggers Note Off - Automatically terminates Tremolo Loops according to SF2 spec
+   */
+  noteOff(channel, pitch) {
+    if (!this.synthInstanceAvailable()) return;
+
+    const midiPitch = Math.min(127, Math.max(0, parseInt(pitch, 10)));
+
+    // Execute Note Off - FluidSynth C++ terminates loops and processes Release Envelope
+    this.fluidModule._fluid_synth_noteoff(this.synthPtr, channel, midiPitch);
+  }
+
+  /**
+   * Emergency Panic Button / Stop All Notes
+   */
+  stopAllNotes() {
+    if (!this.synthInstanceAvailable()) return;
+    for (let ch = 0; ch < 16; ch++) {
+      this.fluidModule._fluid_synth_all_notes_off(this.synthPtr, ch);
+      this.fluidModule._fluid_synth_all_sounds_off(this.synthPtr, ch);
+    }
+    console.log("[SonicSF] FluidSynth: All notes stopped.");
+  }
+
+  synthInstanceAvailable() {
+    return this.isInitialized && this.synthPtr !== null && this.fluidModule !== null;
+  }
+}
+
+export const soundFontPlayerInstance = new FluidSynthWasmPlayer();
+
+```
+
+---
+
+## 4. WORKLET PROCESSOR CREATION (`fluidsynth-processor.js`)
+
+Create a new file at `app/static/js/worklets/fluidsynth-processor.js` to handle real-time audio rendering loops without blocking the UI Thread:
+
+```javascript
+// app/static/js/worklets/fluidsynth-processor.js
+
+class FluidSynthProcessor extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.synthPtr = null;
+    this.wasmModule = null;
+
+    this.port.onmessage = (e) => {
+      if (e.data.type === 'INIT_SYNTH') {
+        this.wasmModule = e.data.wasmModule;
+        this.synthPtr = e.data.synthPtr;
+      }
+    };
+  }
+
+  process(inputs, outputs, parameters) {
+    const output = outputs[0];
+    if (!output || output.length < 2 || !this.synthPtr || !this.wasmModule) {
+      return true;
+    }
+
+    const leftChannel = output[0];
+    const rightChannel = output[1];
+    const bufferSize = leftChannel.length; // 128 samples per render frame
+
+    // Call C++ function _fluid_synth_write_float to render real-time PCM audio
+    // Prevents audio tearing and Thread bottlenecks
+    this.wasmModule._fluid_synth_write_float(
+      this.synthPtr,
+      bufferSize,
+      leftChannel.byteOffset, 0, 1,
+      rightChannel.byteOffset, 0, 1
+    );
+
+    return true;
+  }
+}
+
+registerProcessor('fluidsynth-processor', FluidSynthProcessor);
+
+```
+
+---
+
+## 5. EMBEDDING FLUIDSYNTH WASM BUILD IN HTML
+
+Add the compiled C++ script wrapper inside the `<head>` tag of `index.html`:
+
+```html
+<!-- app/templates/index.html -->
+<script src="https://cdn.jsdelivr.net/npm/fluidsynth-wasm@latest/dist/fluidsynth.js"></script>
+
+```
+
+---
+
+## 6. POST-MIGRATION TECHNICAL BENEFITS
+
+* **$100\%$ Resolution of Tremolo/Sustain Note Sticking:** `noteOff` signals smoothly release active loops according to original SoundFont ADSR Envelope parameters.
+* **Client & Server Parity:** Client Preview (Wasm) and Server WAV Export (Python `pyfluidsynth`) share the exact same C++ Core Engine of FluidSynth, ensuring identical $100\%$ audio reproduction parity.
+* **Sample-Accurate Performance:** Direct execution inside AudioWorklet PCM Buffers minimizes playback latency down to $0\text{ms}$.

requirements.txt

@@ -14,3 +14,4 @@ jsonschema>=4.18.0
 pedalboard>=0.8.0
 mido>=1.3.0
 pyfluidsynth>=1.3.0
+sf2utils>=0.9.0

wiki.md

@@ -1,3 +1,57 @@
+### [2026-07-26 18:05] Task: Fix SpessaSynth CDN 404 + AudioWorklet init
+- **Tóm tắt thay đổi:** Sửa CDN URL từ `@latest/dist/spessasynth_lib.js` (404) → `@4.3.1/dist/index.js` (200). Dùng `WorkletSynthesizer` class + `audioWorklet.addModule(processor.min.js)`, `soundBankManager.addSoundBank()`, `await isReady`. Fallback WorkerSynthesizer nếu AudioWorklet không khả dụng.
+- **Các file ảnh hưởng:** `app/templates/index.html`, `app/static/js/services/soundfontPlayer.js`, `app/static/js/app.precompiled.js`
+- **Ghi chú/Test (nếu có):** SpessaSynth CDN load OK (200). Cần kiểm tra browser console.
+---
+
+### [2026-07-26 20:15] Task: Stabilize client preview (oscillator + FluidSynth server)
+- **Tóm tắt thay đổi:** Kết luận sau debug: SpessaSynth parser (fromArrayBuffer) không extract được presets từ SF2. Client luôn dùng oscillator (ADSR theo program). Server-side FluidSynth render cho âm thanh chính xác khi Export. Xoá debug logs, clean code.
+- **Các file ảnh hưởng:** `app/static/js/services/soundfontPlayer.js`, `app/api/v1/plugins.py`, `app/static/js/app.precompiled.js`
+- **Ghi chú/Test (nếu có):** Preview qua oscillator luôn có âm thanh. Export WAV dùng FluidSynth với SoundFont thật.
+---
+
+### [2026-07-26 17:50] Task: Implement SF3 conversion + SpessaSynth client player
+- **Tóm tắt thay đổi:** Python SF2→SF3 converter (ffmpeg Ogg Vorbis), startup auto-convert, download endpoint ưu tiên SF3. Client: IndexedDB cache, soundfontPlayer.js dual-mode (SpessaSynth + oscillator fallback), init + loadSF trong app.jsx.
+- **Các file ảnh hưởng:** `Dockerfile`, `app/core/soundfont_converter.py` (NEW), `app/api/v1/plugins.py`, `app/main.py`, `app/templates/index.html`, `app/static/js/services/soundfontStorage.js` (NEW), `app/static/js/services/soundfontPlayer.js`, `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** DSK 11M→1.1MB (90%), SGM 529M→18MB (97%). SpessaSynth load từ CDN. Fallback oscillator nếu offline.
+---
+
+### [2026-07-26 17:25] Task: Fix duplicate Synth + MIDI keyboard silent handler
+- **Tóm tắt thay đổi:** Xoá nút Synth nhỏ giữa ARM và Monitor (dư thừa). Sửa MIDI keyboard handler: bỏ try/catch rỗng, thêm fallback tìm track armed trong main session, pass synth_engine context.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** ARM track → MIDI keyboard → playNote với instrument đã chọn. Server render dùng đúng SGM/SoundFont; client preview dùng oscillator emulation (giới hạn browser).
+---
+
+### [2026-07-26 17:20] Task: MIDI keyboard plays selected instrument on armed main track
+- **Tóm tắt thay đổi:** Khi ARM track trong MAIN SESSION/SECTION-TAB, nhấn MIDI Keyboard sẽ play note với instrument đã chọn (synth_engine/instrumentProgram). Fallback: nếu không có sub-tab PIANO_ROLL nào đang armed, tìm track đã ARM trong main session và dùng instrument của nó. Audio routing qua track's gainNode nếu có.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** ARM track → chọn SF instrument → bấm MIDI keyboard → nghe âm thanh instrument đã chọn.
+---
+
+### [2026-07-26 17:10] Task: Add Drum channel toggle on track panel
+- **Tóm tắt thay đổi:** Thêm button 🥁 trên track panel (giữa Solo và Record) để chuyển track sang drum channel 9. Khi active: set `is_percussion=true`, `soundfont_bank=128`. Thêm 🥁 indicator cho percussion presets (bank=128) trong instrument selector.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** Click 🥁 → track chuyển drum mode → render chạy channel 9.
+---
+
+### [2026-07-26 17:05] Task: Fix FluidSynth API mismatch (silent fallback)
+- **Tóm tắt thay đổi:** Pyfluidsynth thực tế là low-level CFFI wrapper, không có class `FluidSynth()`. Dùng sai API → tất cả SoundFont render fallback về oscillator (silence). Fix: dùng `new_fluid_synth`, `fluid_synth_sfload`, `fluid_synth_program_select`, `fluid_synth_write_s16_stereo`. Đồng bộ internal clock bằng cách render silence qua `write_s16_stereo` thay vì chỉ advance cursor.
+- **Các file ảnh hưởng:** `app/core/render_engine.py`
+- **Ghi chú/Test (nếu có):** DSK BAN-DI (prog=5) và SGM Brass (prog=56) đều có audio riêng biệt. Render peak ~0.04-0.056, spectral profile khác nhau rõ rệt.
+---
+
+### [2026-07-26 16:55] Task: Fix SoundFont program selection flow
+- **Tóm tắt thay đổi:** Sửa `_find_sf2_path` case-insensitive (catalog IDs lowercase vs filename mixed-case), thêm `synth_engine`, `soundfont_id`, `instrument_source` vào serialize/deserialize để project save/load không mất instrument selection.
+- **Các file ảnh hưởng:** `app/core/render_engine.py`, `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** Verified: `_find_sf2_path('sgm_v2.01')` → `SGM_v2.01.sf2`, render flat fields + synth_engine struct + roundtrip serialization all pass.
+---
+
+### [2026-07-26 16:45] Task: Implement VST3/SoundFont engine plan
+- **Tóm tắt thay đổi:** Fix SF2 path resolution (hardcoded → multi-dir scan), add `synth_engine` struct parsing in render & UI, 3-level fallback chain, pass context to client SoundFont player.
+- **Các file ảnh hưởng:** `app/core/render_engine.py`, `app/static/js/app.jsx`, `app/static/js/services/soundfontPlayer.js`, `app/static/js/services/aiGateway.js`
+- **Ghi chú/Test (nếu có):** Verified: catalog API returns 31 condensed instruments, render with flat fields + synth_engine struct + drums (bank=128) + missing SF fallback all succeed.
+---
+
 ### [2026-07-25 06:57] Task: Fix Piano Roll runtime errors (rollBeats TDZ + handleCCMouseMove)
 - **Tóm tắt thay đổi:** Sửa lỗi `Cannot access 'rollBeats' before initialization` bằng cách di chuyển khai báo `rollBeats`/`rollBeatsRef` lên trước `totalBeats`. Thêm hàm `handleCCMouseMove` bị thiếu và cập nhật `handleCCMouseDown` hỗ trợ Ctrl+Click paint velocity.
 - **Các file ảnh hưởng:** `app/static/js/app.jsx`, `app/static/js/app.precompiled.js`
@@ -270,3 +324,128 @@
 - **Tóm tắt thay đổi:** (1) Sub-tab loop selection chỉ active khi nút Loop (st.isLooping) bật — không còn bị ảnh hưởng bởi global isLoopingSelection. (2) Stop dừng ngay lập tức: `SonicSF.stopAll()` set gain 0 và stop oscillator tại ctx.currentTime, không ramp.
 - **Các file ảnh hưởng:** `app/static/js/app.jsx`, `app/static/js/services/soundfontPlayer.js`, `app/static/js/app.precompiled.js`
 - **Ghi chú/Test (nếu có):** `npm run build` pass.
+
+### [2026-07-26 12:31] Task: VST/SoundFont inspection engine + AI schema
+- **Summary:** New `SoundFontInspector` (sf2utils) scans .sf2 files, generates full/condensed catalog. Added `/soundfonts/catalog` API. Updated AI tool schema with `soundfont_id/bank/program`. Condensed catalog auto-injected into system prompt. Server render now passes bank/program + MIDI channel routing (drums → ch9). Added `DecentSamplerManager` + Pianobook render path. Client `SonicSF`: `applyAITrackInstrument`, `controllerChange`, `programChange`. Catalog cache invalidated on upload.
+- **Files:** `requirements.txt`, `app/core/soundfont_inspector.py` (new), `app/api/v1/plugins.py`, `app/core/vst_engine.py`, `app/core/render_engine.py`, `app/static/js/services/aiGateway.js`, `app/static/js/services/api.js`, `app/static/js/services/soundfontPlayer.js`, `app/static/js/app.jsx`, `Dockerfile`, `.gitignore`, `vst_plugins/` (new), `samples/pianobook/` (new)
+- **Tests:** `python3 -m pytest tests/ -v` → 61 passed, 1 pre-existing failure. Python syntax check OK on all modified files.
+---
+
+### [2026-07-26 16:11] Task: Mount daw_assets host dirs into Docker
+- **Summary:** Created `/home/locpham/daw_assets/{vst3,soundfonts,pianobook}` on host. Mounted them into `web`, `worker`, and `beat` containers at `/opt/daw_engine/vst3`, `/opt/daw_engine/soundfonts`, `/opt/daw_engine/samples/pianobook`.
+- **Files:** `docker-compose.yml`
+- **Tests:** N/A
+---
+
+### [2026-07-26 16:21] Task: Implement Synth button with VST3 selection
+- **Summary:** Fixed Synth button to properly select and use system-installed VST3 plugins. Fixed field name mismatch (`instrument_id` vs `instrument`) between UI and render engine. Track auto-switches to MIDI type when VST assigned. SoundFont preset selection now passes `soundfont_bank` + `soundfont_program` to server. Serialize/deserialize includes all instrument fields.
+- **Files:** `app/static/js/app.jsx`, `app/static/js/app.precompiled.js`, `app/core/render_engine.py`
+- **Tests:** `pytest` - 61 passed, 1 pre-existing failure.
+---
+
+### [2026-07-26 20:45] Task: Fix timeline play — schedule noteOn via setTimeout
+- **Tóm tắt thay đổi:** SpessaSynth noteOn(ch, pitch, vel, enableReverb) không nhận exactAudioTime. Timeline truyền startTime vào vị trí thứ 4 → SpessaSynth ép kiểu thành enableReverb=true → tất cả notes play ở T=0. Fix: tính delay = startTime - currentTime, dùng setTimeout để schedule noteOn đúng thời điểm.
+- **Các file ảnh hưởng:** app/static/js/services/soundfontPlayer.js, app/static/js/app.precompiled.js
+- **Ghi chú/Test (nếu có):** MIDI keyboard play ngay. Timeline play các note đúng thời điểm.
+---
+
+### [2026-07-26 21:00] Task: Sync loop button + auto-derive loop boundaries
+- **Tóm tắt thay đổi:** Nút Loop trên transport controls giờ đồng bộ với sub-tab đang active. Khi bật loop: tự động tính loopEnd từ MIDI notes, section clips, hoặc audio duration. Gán selectionStart=0, selectionEnd=loopEndTime. Main timeline cũng tự derive loop end từ tracks/items/clips.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** Bật Loop → playhead loop từ đầu đến cuối item/clip và ngược lại.
+
+### [2026-07-26 21:15] Task: Fix stop + loop for all tab types
+- **Tóm tắt thay đổi:** `stopAll` giờ huỷ tất cả `setTimeout` đã schedule cho SpessaSynth notes (cả noteOn lẫn noteOff), gọi `allNotesOff(0-15)`. Loop hoạt động trên MAIN SESSION (qua `isLoopingSelection` + `selLeft/selRight`), SECTION-TAB và PIANO_ROLL (qua `st.isLooping` + `st.selectionStart/End`).
+- **Các file ảnh hưởng:** `app/static/js/services/soundfontPlayer.js`, `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** Stop = dừng ngay. Loop = phát từ đầu đến cuối item/clip rồi lặp lại.
+
+### [2026-07-26 21:30] Task: Sticky ruler + tempo lane on track scroll
+- **Tóm tắt thay đổi:** Wrap TimelineRuler và TempoTrackLane trong `sticky top-0 z-30 bg-[#1a1a1a]`. Khi cuộn tracks lên, ruler và tempo lane vẫn hiển thị dưới toolbar. Áp dụng cho cả MAIN SESSION và sub-tab views.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** Cuộn tracks lên → ruler + tempo lane dính ở top.
+
+### [2026-07-26 22:05] Task: Fix multi-track bank loading (no delete, graceful 404)
+- **Tóm tắt thay đổi:** Xoá `deleteSoundBank` — SpessaSynth giữ nhiều banks đồng thời. Kiểm tra `soundBankList` trước khi tải lại. 404 từ server không làm mất bank đã load trước đó.
+- **Các file ảnh hưởng:** `app/static/js/services/soundfontPlayer.js`
+- **Ghi chú/Test (nếu có):** 3 tracks với 3 SF khác nhau → SpessaSynth giữ cả 3 → noteOn dùng đúng preset từ bank tương ứng.
+
+### [2026-07-27 07:55] Task: Fix item duration when BPM changes
+- **Tóm tắt thay đổi:** Thêm `length_bars` vào midiItems/sections. `useEffect` trên BPM recalc `duration = length_bars * currentSecondsPerBar`. Fix section hardcoded 4s → `4 * secondsPerBar`.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** Tạo 8 bars item ở BPM 80 → đổi BPM 120 → item vẫn 8 bars.
+
+### [2026-07-27 08:20] Task: Fix TempoTrackLane bar spacing on BPM change
+- **Tóm tắt thay đổi:** DOM traversal tìm scrollLeft bị gãy do sticky wrapper (tìm nhầm div có `position: sticky` với scrollLeft=0). Xoá DOM lookup, dùng `scrollLeft` prop trực tiếp. Fix cho cả TimelineRuler và TempoTrackLane.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** Thay đổi BPM → bars trên tempo track lane vẽ đúng khoảng cách.
+
+### [2026-07-27 08:25] Task: Fix bar width drift for non-integer BPM
+- **Tóm tắt thay đổi:** Vòng lặp `t += beatDuration` tích luỹ sai số dấu phẩy động (đặc biệt BPM lẻ như 77, 81). Chuyển sang `t = bn * beatDuration` với bn là số beat nguyên — mỗi bar line tính độc lập, không sai số tích luỹ.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** BPM 77 → tất cả bars đều rộng bằng nhau.
+
+### [2026-07-27 08:40] Task: TimelineRuler draws bar markers aligned with TempoTrackLane
+- **Tóm tắt thay đổi:** Thêm bar markers vào TimelineRuler dùng cùng `bn * barDuration` với TempoTrackLane. Số bar hiển thị ở giữa ruler. Time markers vẫn giữ phía dưới. Cùng BPM prop → luôn đồng bộ với tempo track.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx`
+- **Ghi chú/Test (nếu có):** Thay đổi BPM → TimeRuler bars + TempoTrackLane bars luôn đồng nhất.
+
+### [2026-07-27 08:48] Fix: equal bar widths + selection tempo/time mode
+- **WaveformLane:** Integer beat loop thay vì `t += beatDuration` (fix bar width drift)
+- **Selection mode:** Nút toggle ♪T (theo tempo - đổi BPM → selection thay đổi) / ⏱T (cố định thời gian)
+
+### [2026-07-27 09:25] Feat: eager soundfont scan at startup
+- **App load**: fetch full catalog with all instrument presets
+- **Merge**: gán presets vào từng soundfont trong instrumentSelectorData
+- **Synth button**: hiển thị presets từ cache, không cần API call per-SF
+
+### [2026-07-27 09:55] Feat: Synth button shows flat instrument list from all SFs
+- **openInstrumentSelector**: flatten presets from all SFs + soundfont name tag
+- **Modal**: search bar + flat instrument list + soundfont name prefix
+- **Fix**: `2ad2922` had extra closing paren in PluginManagerModal (build fix)
+- **Arch**: loại bỏ hai-bước, click Synth → chọn instrument trực tiếp
+
+### [2026-07-27 11:05] Feat: MIDI keyboard NoteOff sustain + CC/pitch bend realtime
+- **NoteOff**: durationMs=60000, NoteOff gọi stopNote(ch,pitch) → note tắt ngay
+- **MIDI channel**: truyền msg.data[0]&0x0F vào playNote/stopNote
+- **CC64 sustain/CC1 modulation**: forward qua SonicSF.controllerChange
+- **Pitch Bend**: forward qua SonicSF.pitchBend (14-bit)
+
+### [2026-07-27 11:20] Fix: All Notes Off (CC123) before MIDI NoteOn
+- **Nguyên nhân:** SoundFonts như saxophone có release envelope dài, noteOff không tắt âm ngay
+- **Fix:** Gửi `controllerChange(ch, 123, 0)` = All Notes Off trước mỗi NoteOn từ MIDI keyboard
+- **Kết quả:** Note trước tắt ngay khi play note mới, không còn đè âm
+
+### [2026-07-27 11:45] Fix: lazyInit in playNote + 3 root cause fixes
+- **Root cause 1:** NoteOn with velocity=0 treated as NoteOff ✅ (cmd === 0x8 || (cmd === 0x9 && vel === 0))
+- **Root cause 2:** Same channel extraction for NoteOn+NoteOff ✅ (msg.data[0] & 0x0F)
+- **Root cause 3:** pitch/channel always integers from msg.data[] ✅
+- **Added:** _lazyInit() called from playNote when _initialized false
+- **Oscillator fallback:** 2000ms instead of 60000ms (quick preview before init)
+
+### [2026-07-27 12:05] Task: Fix Tremolo String continuous sustain after MIDI note-off
+- **Tóm tắt thay đổi:** Root cause: `stopNote()` used CC 123 (All Notes Off) which merely enters SoundFont's release envelope. Sustained instruments like Tremolo Strings (GM#44) have 2-5s release tails. Fix: replaced CC 123 with CC 120 (All Sound Off) in `stopNote()` and `stopAll()`. CC 120 sets `voice.isActive = false` immediately, bypassing the release envelope entirely, so the note stops instantly on key release.
+- **Các file ảnh hưởng:** `app/static/js/services/soundfontPlayer.js`
+- **Ghi chú/Test (nếu có):** Test với MIDI keyboard + Tremolo Strings instrument: note tắt ngay khi release key. CC 120 tác dụng lên toàn bộ channel (kill all voices) — phù hợp với keyboard preview use-case.
+
+### [2026-07-27 12:45] Task: Migrate SpessaSynth → FluidSynth WASM engine
+- **Tóm tắt thay đổi:** Thay thế SpessaSynth (JS/AudioWorklet) bằng FluidSynth WASM (C++ compiled via Emscripten). CDN `@enikey87/fluidsynth-emscripten@0.1.1` cho dev (localhost), self-host `/static/js/vendor/` cho production. Giải quyết triệt để stuck notes (Tremolo/Saxophone) nhờ FluidSynth xử lý Gen 44 loop mode chuẩn SF2.04. Thêm `fluidsynth-bridge.js` AudioWorklet nhận PCM từ main-thread FluidSynth render loop. Giữ nguyên `window.SonicSF` API surface (0 thay đổi ở app.jsx).
+- **Các file ảnh hưởng:** `app/static/js/services/soundfontPlayer.js`, `app/templates/index.html`, `app/static/js/services/fluidsynthLoader.js` (NEW), `app/static/js/worklets/fluidsynth-bridge.js` (NEW), `app/static/js/vendor/libfluidsynth-2.3.0-sf3.js` (NEW), `app/static/js/vendor/libfluidsynth-2.3.0-sf3.wasm` (NEW)
+- **Ghi chú/Test (nếu có):** Server render (pyfluidsynth) + client preview (FluidSynth WASM) = cùng C++ core → 100% audio parity. Cần clear browser cache. Babel 8 syntax error pre-existing (JSX `{ if(...) { } }` trong app.jsx), không rebuild được app.precompiled.js.
+---
+
+### [2026-07-27 15:59] Fix: _activeNotes array — multi-track ARM cùng pitch
+- **Tóm tắt thay đổi:** Khi 2 track ARM play cùng MIDI pitch, `_activeNotes['0:60']` bị overwrite (track2 ghi đè track1). `stopNote` chỉ stop 1 track. Fix: `_activeNotes[key] = [ch1, ch2, ...]` array. `stopNote` iterate all channels.
+- **Các file ảnh hưởng:** `soundfontPlayer.js`
+- **Ghi chú/Test (nếu có):** ARM 2 track, play note → thả phím → cả 2 track stop.
+---
+
+### [2026-07-27 15:47] Fix: Multi-track ARM + activeNotes cho stopNote
+- **Tóm tắt thay đổi:** MIDI handler `find(t=>isArmed)` → `filter(...)` loop all armed tracks. Thêm `_activeNotes[ch:pitch]` map để `stopNote` lookup đúng channel sau khi đổi SoundFont (channel allocation thay đổi).
+- **Các file ảnh hưởng:** `soundfontPlayer.js`, `app.precompiled.js`
+- **Ghi chú/Test (nếu có):** ARM 2 track cùng SF khác instrument → cả 2 play. Đổi SF → noteOff vẫn tìm đúng voice.
+---
+
+### [2026-07-27 12:15] Task: Fix SpessaSynth loop voice not releasing (layer 2)
+- **Tóm tắt thay đổi:** CC 120 vẫn không đủ vì SpessaSynth 4.3.1 AudioWorklet có bug: looped voices trong MIDI message pipeline xử lý CC 120 sai (`processMessage`). Fix: thêm `noteOn(ch, pitch, 0)` (MIDI noteOff alternate path) + `_synthInstance.post({channelNumber:ch, type:"stopAll", data:1})` gửi lệnh trực tiếp đến worklet qua `handleMessage` — bypass hoàn toàn MIDI pipeline.
+- **Các file ảnh hưởng:** `app/static/js/services/soundfontPlayer.js`, `app/templates/index.html`
+- **Ghi chú/Test (nếu có):** Cần clear cache browser (index.html cache-bust param updated).