IMPROVE: PIANO ROLL TAB khi play thì playhead luôn nằm chính giữa piano roll

Replace single-track solo (radio) with multi-solo toggle.
No longer clears solo on other tracks when toggling one track.

.gitignore

@@ -17,7 +17,13 @@ app/storage/uploads/*
 app/storage/processed/*
 !app/storage/uploads/.gitkeep
 !app/storage/processed/.gitkeep
+app/storage/*.db
+app/storage/sf_scan_state.json
 .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.
+

.kilo/plans/1785145662134-midi-ghost-note-plan.md

@@ -0,0 +1,287 @@
+# Plan: MIDI Ghost Notes + Dropdown Item Switcher + Session Sync Mode
+
+## Overview
+Three features built on each other:
+1. **Dropdown** at tab title position listing ALL MIDI items across all tracks
+2. **Item switching** — selected item becomes editable, all others become ghost notes
+3. **Session sync mode toggle** — viewport aligns with session bars (ghost visible) or resets to bar 0 (isolated, no ghost)
+
+---
+
+## Key Design Decisions
+
+### A. Ghost note scope = all items except the selected one
+Not just "other tracks" — ALL MIDI items in `activeTracks` except the one matching `targetItemId` contribute ghost notes if overlapping.
+
+### B. Two viewport modes, togglable
+| Mode | Viewport origin | Ghost notes | Bar labels |
+|------|----------------|-------------|------------|
+| **Session Sync** (default) | `item.startTime / secondsPerBar` | Visible | `Bar N` (session-absolute) |
+| **Isolated** | bar 0 | Hidden | `Bar N` (0-based) |
+
+### C. Ghost notes computed (not persisted)
+No schema changes. Extraction runs in `useMemo` inside `PianoRollTabEditor`.
+
+### D. Hit-testing exclusion is automatic
+Ghost notes are in separate `ghostLayers` state; mouse handlers only iterate `notes`.
+
+---
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| **NEW** `app/static/js/services/ghostNoteExtractor.js` | Extraction logic |
+| `app/static/js/app.jsx` (~16113) | Pass `activeTracks` prop to `PianoRollTabEditor` |
+| `app/static/js/app.jsx` (~4563-6070) | All PianoRollTabEditor changes below |
+
+---
+
+## Step-by-Step Implementation
+
+### Step 1: Create `ghostNoteExtractor.js`
+
+`app/static/js/services/ghostNoteExtractor.js`
+
+```js
+export function extractGhostLayers(activeTracks, targetTrackId, targetItemId, bpm)
+```
+
+Algorithm:
+1. `secondsPerBeat = 60 / bpm`
+2. Find `targetItem` across all tracks → `windowStartBeat = targetItem.startTime / secondsPerBeat`, `windowEndBeat = (targetItem.startTime + targetItem.duration) / secondsPerBeat`
+3. Iterate ALL tracks, ALL MIDI items:
+   - Skip non-MIDI tracks (`!t.midiItems || !t.midiItems.length`)
+   - Skip muted tracks (`t.muted`)
+   - Skip item matching `targetItemId` (the active item)
+4. For each candidate item:
+   - `itemStartBeat = item.startTime / secondsPerBeat`
+   - `itemEndBeat = (item.startTime + item.duration) / secondsPerBeat`
+   - Overlap test: `itemStartBeat < windowEndBeat && itemEndBeat > windowStartBeat`
+   - For each overlapping note:
+     - `noteAbsStart = itemStartBeat + note.start_beat`
+     - `noteAbsEnd = noteAbsStart + note.duration_beats`
+     - Clip: keep if `noteAbsStart < windowEndBeat && noteAbsEnd > windowStartBeat`
+     - `clampedDur = Math.min(noteAbsEnd, windowEndBeat) - Math.max(noteAbsStart, windowStartBeat)`
+     - Push: `{ id: ghost_${note.id}, pitch, relative_start_beat: noteAbsStart - windowStartBeat, duration_beats: clampedDur, velocity, original_track_name: t.name, original_track_color: t.color || '#888' }`
+5. Group by track → `ghostLayers: [{ track_id, track_name, track_color, notes }]`
+6. Return `ghostLayers`
+
+### Step 2: Pass `activeTracks` to PianoRollTabEditor
+
+At render site (~line 16113), add:
+```js
+activeTracks: activeTracks,
+```
+
+Add `activeTracks` to destructured props in `PianoRollTabEditor` function signature (~line 4563).
+
+### Step 3: New state & derived data
+
+Inside `PianoRollTabEditor` (~line 4570), after existing `React.useState` declarations:
+
+```js
+const [showGhostNotes, setShowGhostNotes] = React.useState(true);
+const [sessionSyncMode, setSessionSyncMode] = React.useState(true);
+
+// Compute all MIDI items for dropdown
+const allMidiItems = React.useMemo(() => {
+    const result = [];
+    (activeTracks || []).forEach(t => {
+        if (!t.midiItems || !t.midiItems.length) return;
+        t.midiItems.forEach(m => {
+            result.push({ ...m, _trackId: t.id, _trackName: t.name });
+        });
+    });
+    return result;
+}, [activeTracks]);
+
+// Compute ghost layers
+const ghostLayers = React.useMemo(() => {
+    if (!activeTracks || !st || !st.target_id) return [];
+    return extractGhostLayers(activeTracks, st.trackId, st.target_id, parseInt(bpm) || 120);
+}, [activeTracks, st.trackId, st.target_id, bpm]);
+
+// Compute session offset for bar labels
+const secondsPerBar = (60.0 / (parseInt(bpm) || 120)) * 4;
+const targetTrack = React.useMemo(
+    () => (activeTracks || []).find(t => t.id === st.trackId),
+    [activeTracks, st.trackId]
+);
+const activeTargetItem = React.useMemo(
+    () => targetTrack ? (targetTrack.midiItems || []).find(m => m.id === st.target_id) : null,
+    [targetTrack, st.target_id]
+);
+const sessionStartBar = sessionSyncMode && activeTargetItem
+    ? (activeTargetItem.startTime / secondsPerBar) : 0;
+```
+
+### Step 4: Dropdown at tab title position
+
+Replace the static title (line 5748-5752) with a dropdown:
+
+```js
+/* 1a. TAB TITLE DROPDOWN */
+React.createElement("div", { className: "relative inline-block text-xs" },
+    React.createElement("select", {
+        value: st.target_id,
+        onChange: e => handleSwitchMidiItem(e.target.value),
+        className: "bg-zinc-800 border border-zinc-700 text-yellow-500 font-bold rounded px-1.5 py-0.5 outline-none focus:border-yellow-500 max-w-[200px]"
+    }, allMidiItems.map(m => 
+        React.createElement("option", {
+            key: m.id,
+            value: m.id
+        }, `${m._trackName} - ${m.name || 'MIDI'}`)
+    ))
+)
+```
+
+### Step 5: Switch handler function
+
+Add before the return statement:
+
+```js
+const handleSwitchMidiItem = (itemId) => {
+    if (itemId === st.target_id) return;
+    
+    // Save current notes first
+    onSaveNotes(st.id, st.trackId, st.target_id, notes);
+    
+    // Find selected item
+    const match = allMidiItems.find(m => m.id === itemId);
+    if (!match) return;
+    
+    // Update subTab state (triggers ghost re-compute via useMemo)
+    setSubTabs(prev => prev.map(s => s.id === st.id ? {
+        ...s,
+        trackId: match._trackId,
+        target_id: match.id,
+        label: `Piano Roll: ${match.name || 'MIDI'}`,
+        notes: match.notes || [],
+        duration: match.duration || 4,
+        instrumentProgram: activeTracks.find(t => t.id === match._trackId)?.instrumentProgram,
+        instrumentName: activeTracks.find(t => t.id === match._trackId)?.instrumentName,
+        note_selection: [],
+        currentTime: 0,
+    } : s));
+    
+    // Reset local state
+    setSelectedNoteIds([]);
+    setLoopStartBeat(null);
+    setLoopEndBeat(null);
+};
+```
+
+### Step 6: Session sync toggle button
+
+In toolbar (~line 5798, near CC toggle), add:
+
+```js
+/* Session sync mode toggle */
+React.createElement("button", {
+    onClick: () => setSessionSyncMode(!sessionSyncMode),
+    className: `px-2 py-1 rounded text-xs ${sessionSyncMode ? 'bg-cyan-900/60 text-cyan-300 border border-cyan-700' : 'text-zinc-500 hover:text-zinc-300'}`,
+    title: sessionSyncMode ? "Session-synced mode (ghost visible)" : "Isolated mode (bar 0, no ghost)"
+}, sessionSyncMode ? "🌐 Session" : "📋 Isolated")
+```
+
+And the Ghost toggle:
+
+```js
+React.createElement("button", {
+    onClick: () => setShowGhostNotes(!showGhostNotes),
+    disabled: !sessionSyncMode,
+    className: `px-2 py-1 rounded text-xs ${!sessionSyncMode ? 'opacity-30 cursor-not-allowed' : showGhostNotes ? 'bg-purple-900/60 text-purple-300 border border-purple-700' : 'text-zinc-500 hover:text-zinc-300'}`,
+    title: "Toggle ghost notes visibility"
+}, "👻 Ghost")
+```
+
+Ghost toggle disabled in isolated mode (no ghost notes to show).
+
+### Step 7: Bar labels with session offset
+
+Modify `renderBarLabels()` (~line 5711-5734):
+
+Replace `Bar ${bar}` with:
+```js
+const displayBar = bar + Math.floor(sessionStartBar);
+`Bar ${displayBar}`
+```
+
+And the seek click handler:
+```js
+const barTime = (bar + Math.floor(sessionStartBar)) * 4 * beatSec;
+```
+
+### Step 8: Auto-scroll to session position
+
+Add `useEffect`:
+
+```js
+React.useEffect(() => {
+    if (sessionSyncMode && gridScrollRef.current && activeTargetItem) {
+        const scrollTargetBeats = sessionStartBar * 4;
+        gridScrollRef.current.scrollLeft = scrollTargetBeats * pixelsPerBeat;
+    }
+}, [sessionSyncMode, sessionStartBar, st.target_id, pixelsPerBeat]);
+```
+
+### Step 9: Ghost note canvas layer
+
+In the note-drawing `useLayoutEffect` (~line 4834), insert **before** active note rendering:
+
+```js
+/* Layer 2: Ghost Notes */
+if (showGhostNotes && sessionSyncMode && ghostLayers.length > 0) {
+    ghostLayers.forEach(layer => {
+        ctx.save();
+        ctx.globalAlpha = 0.25;
+        ctx.fillStyle = layer.track_color || '#888';
+        ctx.strokeStyle = layer.track_color || '#888';
+        layer.notes.forEach(note => {
+            const x = note.relative_start_beat * pixelsPerBeat;
+            const y = (127 - note.pitch) * NoteHeight;
+            const w = note.duration_beats * pixelsPerBeat;
+            const h = NoteHeight - 1;
+            ctx.fillRect(x, y, w, h);
+            ctx.setLineDash([2, 2]);
+            ctx.lineWidth = 1;
+            ctx.strokeRect(x, y, w, h);
+            ctx.setLineDash([]);
+        });
+        ctx.restore();
+    });
+}
+```
+
+Add `showGhostNotes`, `sessionSyncMode`, `ghostLayers` to dependency array.
+
+### Step 10: Ghost notes in CC Lane
+
+Skip ghost notes in CC lane (only active notes). CC lane already only iterates `notes`, not `ghostLayers`. No changes needed.
+
+---
+
+## Edge Cases
+
+- **Dropdown with single MIDI item**: Only one option, no ghost notes (nothing to ghost).
+- **Item deleted while piano roll is open**: `handleSwitchMidiItem` fails gracefully (item not found → no-op). `ghostLayers` `useMemo` returns `[]`.
+- **BPM change mid-edit**: All beat computations update via `useMemo`/React reactivity.
+- **Session sync → Isolated switch**: Scroll resets to 0, bar labels change to 0-based, ghost notes disappear.
+- **Isolated → Session sync switch**: Scroll jumps to session position, ghost notes reappear.
+- **Color fallback**: Use track's `color` prop; if `#888` as default.
+
+---
+
+## Validation
+
+1. Open MIDI item → dropdown shows all MIDI items across all tracks
+2. Select different item from dropdown → active notes switch, ghost notes re-compute
+3. Ghost notes from ALL non-selected items appear (same track + other tracks)
+4. Ghost toggle hides/shows ghost notes (disabled in isolated mode)
+5. Session sync mode shows correct bar labels (e.g. `Bar 2` if item starts at bar 2)
+6. Isolated mode shows `Bar 0, 1, 2...` regardless of item's session position
+7. Switching items in isolated mode: notes change, viewport stays at bar 0
+8. Ghost notes cannot be clicked/dragged (excluded from hit-testing)
+9. Muted tracks' MIDI items are excluded from ghost notes
+10. Items outside target window are excluded from ghost notes

.kilo/plans/1785323991986-mastering-module-plan.md

@@ -0,0 +1,197 @@
+# Implementation Plan: Ozone Mastering Module
+
+## Nguồn DUY NHẤT để tạo giao diện
+
+**Toàn bộ giao diện của Mastering Modal được lấy TRỰC TIẾP từ HTML trong `md/45_MASTERING_MODULE.md` dòng 74–885.**
+
+Không thiết kế giao diện mới. Không suy luận UI. Lấy chính xác:
+- **Cấu trúc HTML**: copy verbatim từ spec, chuyển sang JSX (className thay class, onChange thay onchange, v.v.)
+- **CSS styles**: copy verbatim từ spec (oz-panel, oz-card, oz-card-active, knob-dial, knob-pointer, gradient backgrounds)
+- **JavaScript logic**: port verbatim từ spec vào React hooks (useState thay ozState, useRef thay DOM refs, useEffect thay event listeners)
+- **Web Audio DSP graph**: copy y hệt node graph + connection từ spec (BiquadFilterNode, GainNode, DynamicsCompressorNode, AnalyserNode)
+- **Canvas renderers**: copy y hệt drawing logic từ spec (frequency grid, FFT fill, EQ curve, polar vectorscope, VU meter gradient)
+
+## Goal
+Dịch spec HTML `md/45_MASTERING_MODULE.md` (lines 74–885) thành `MasteringModal` React component trong `app.jsx`.
+
+## Ánh xạ HTML → React (chi tiết từ spec)
+
+### HTML lines 74–118: Dependencies & Styles
+
+| Spec | Action |
+|------|--------|
+| `<script src="cdn.tailwindcss.com">` | Đã có trong `index.html:9` |
+| `<link FA 6.4.0>` | Đã có trong `index.html:10` (dùng lucide thay FA, giữ nguyên) |
+| `<link Google Fonts Inter>` | Đã có font-family trong `index.html` style |
+| CSS `.oz-panel` `oz-card` `oz-card-active` `knob-*` scrollbar | Thêm vào `index.html` `<style>` block |
+| CSS `.font-mono { JetBrains Mono }` | Thêm vào `index.html` `<style>` |
+
+**→ Sửa `app/templates/index.html`**: append ~30 dòng CSS class (oz-panel, oz-card, knob-dial, scrollbar tối)
+
+---
+
+### HTML lines 121–161: Header Bar
+
+| Spec Element | React JSX Mapping |
+|---|---|
+| Logo `.fa-atom` + "OZONE ADVANCED" | `<div>` với cùng class & lucide icon `wand-2` thay FA |
+| Play/Stop buttons + preset select | JSX nguyên bản, class giữ nguyên |
+| Target LUFS text | JSX nguyên bản |
+
+**→ Trong `MasteringModal` return JSX**, copy verbatim HTML, chỉ thay `.fa-*` → lucide `i` tương ứng.
+
+---
+
+### HTML lines 163–213: Module Chain Strip
+
+| Spec Element | React |
+|---|---|
+| `#cardDynamicEq` + power toggle + icon | JSX với `onClick` → set activeModule('eq') |
+| `#cardImager` + power toggle + icon | JSX với `onClick` → set activeModule('imager') |
+| `#cardMaximizer` + power toggle + icon | JSX với `onClick` → set activeModule('maximizer') |
+| Empty add-module slot `.border-dashed` | JSX verbatim |
+| `oz-card-active` class toggle | `className={\`oz-card ${ozState.activeModule==='eq' ? 'oz-card-active' : ''}\`}` |
+
+---
+
+### HTML lines 216–325: Dynamic EQ View
+
+| Spec Element | React |
+|---|---|
+| `#viewDynamicEq` container | `className={ozState.activeModule === 'eq' ? '' : 'hidden'}` |
+| `#eqCanvas` | `<canvas ref={el => canvasRefs.current.eq = el}>` |
+| 4-band knobs (Low/Mid1/Mid2/High) | Mỗi band là `<div>` với `.knob-container`, `data-param`, pointer events |
+| Knob dial HTML `.knob-dial > .knob-pointer` | JSX verbatim + inline `transform: rotate(Xdeg)` |
+| Band labels & freq text | JSX verbatim |
+
+**Knob interaction (spec lines 794–843)**: port pointerdown/move/up logic vào `useEffect` với `.knob-container` querySelectorAll, update `ozState[param]` + gọi `updateAudioGraphValues`.
+
+---
+
+### HTML lines 327–363: Stereo Imager View
+
+| Spec Element | React |
+|---|---|
+| `#viewImager` | `className={ozState.activeModule === 'imager' ? '' : 'hidden'}` |
+| `#imagerCanvas` (polar vectorscope) | `<canvas ref={...}>` |
+| 4-band width sliders `#w1Slider`–`#w4Slider` | `<input type="range" value={ozState.w1} onChange={...}>` |
+| Value spans `#w1Val`–`#w4Val` | `<span>{ozState.w1}%</span>` |
+
+---
+
+### HTML lines 366–421: Maximizer View
+
+| Spec Element | React |
+|---|---|
+| `#viewMaximizer` | `className={ozState.activeModule === 'maximizer' ? '' : 'hidden'}` |
+| Maximizer gain knob (`.knob-dial w-24 h-24`) | JSX verbatim, pointer events |
+| Ceiling level text | `<span>{ozState.ceiling.toFixed(2)} dB</span>` |
+| Upward compress knob | JSX verbatim + pointer events |
+| Soft clipper knob | JSX verbatim + pointer events |
+| Transient emphasis knob | JSX verbatim + pointer events |
+
+---
+
+### HTML lines 425–480: Right Sidebar (I/O Meters + Utilities)
+
+| Spec Element | React |
+|---|---|
+| `#inPeakText` / `#outPeakText` | `<span>{inPeak.toFixed(1)} dB</span>` etc. |
+| `#inMeterCanvas` / `#outMeterCanvas` | `<canvas ref={...}>` |
+| Bypass / Gain Match / Codec / Dither buttons | JSX verbatim |
+| Module active state checkboxes (power toggles) | Thêm `onClick` set `ozState.eqActive` etc. + gọi `updateAudioGraphValues` |
+
+---
+
+### HTML lines 484–585: Audio Engine (JavaScript → React)
+
+| Spec Function | React Mapping |
+|---|---|
+| `ozState` object | `const [ozState, setOzState] = useState({...})` — values copy verbatim |
+| `initOzoneAudioEngine()` | `useEffect` on mount: tạo AudioContext (dùng `window.SonicAudio?.getAudioContext()` nếu có), tạo AnalyserNode (fftSize=2048), BiquadFilter nodes (lowshelf 100Hz, peaking 822Hz Q0.7, peaking 3.2kHz Q1.2, highshelf 10kHz), GainNode boost, DynamicsCompressorNode (threshold -0.1, knee 0, ratio 20, attack 0.001, release 0.05), outputAnalyser |
+| Node graph connection | `inputAnalyser → eqLow → eqMid1 → eqMid2 → eqHigh → boostGain → compressor → outputAnalyser → destination` |
+| `updateAudioGraphValues()` | Copy verbatim logic: `eqLowFilter.gain.setTargetAtTime(ozState.eqActive ? ozState.eqLowGain : 0, now, 0.01)` etc. |
+| `startAudioDemo()` | Copy verbatim: create 4-second stereo buffer, kick/snare/synth oscillator, loop playback |
+| `stopAudioDemo()` | Copy verbatim: `sourceNode.stop(); sourceNode.disconnect();` |
+
+---
+
+### HTML lines 586–791: Canvas Renderers (JavaScript → React)
+
+| Spec Canvas | React Mapping |
+|---|---|
+| `eqCanvas` (lines 680–738) | `useEffect` với `requestAnimationFrame` loop: draw freq grid lines, FFT spectrum bar fill từ `outputAnalyser.getByteFrequencyData`, draw composite EQ curve |
+| `imagerCanvas` (lines 742–765) | `requestAnimationFrame`: draw polar circle guides + random scatter dots with `ozState.w3` width |
+| `inMeterCanvas`/`outMeterCanvas` (lines 769–787) | `requestAnimationFrame`: `renderMeterBar()` with linear gradient green→yellow→red, dBFS numeric readout |
+| `resizeAll()` | `useEffect` + `window.addEventListener('resize', resizeAll)` |
+
+---
+
+### HTML lines 793–882: Interactions & Init (JavaScript → React)
+
+| Spec | React |
+|---|---|
+| `setupKnobs()` (lines 794–843) | `useEffect` on mount: query `.knob-container`, attach pointerdown/move/up, update UI rotation + `ozState` + `updateAudioGraphValues` |
+| `setupModuleNavigation()` (lines 846–868) | Inline JSX click handlers thay vì event listeners |
+| `window.addEventListener('load', ...)` (lines 871–882) | `useEffect` on mount: init audio engine, setup event handlers, start canvas renderers |
+
+---
+
+## Task List
+
+### Task 1: Append CSS classes vào app/templates/index.html
+Thêm ~30 dòng CSS vào `<style>` block (`index.html:28-245`):
+- `.oz-panel` `oz-card` `oz-card-active`
+- `.knob-container` `.knob-dial` `.knob-pointer`
+- Scrollbar dark theme
+- `.font-mono` JetBrains Mono override
+- Gradient panel backgrounds
+
+### Task 2: Thêm state + menu item trong app.jsx
+- `showMasteringModal` state (dòng 7708)
+- Menu item "Mastering Suite" (dòng 15585)
+- Render `MasteringModal` (dòng 18664)
+
+### Task 3: Viết MasteringModal component trong app.jsx (trước dòng 6694)
+~500 dòng gồm:
+
+**3a. State**: `ozState` (activeModule, gains, widths, maximizer params), `isPlaying`, `canvasRefs`, `audioRefs`
+
+**3b. useEffect (mount)**: `initOzoneAudioEngine()` — copy verbatim từ spec lines 529-584, dùng `window.SonicAudio?.getAudioContext()` fallback
+
+**3c. useEffect (mount)**: `setupKnobs()` — port pointer events từ spec lines 794-843, gọi `updateAudioGraphValues()` khi giá trị thay đổi
+
+**3d. useEffect (mount + deps)**: Canvas render loop — port `startCanvasRenderers()` từ spec lines 650-791, sử dụng `ozState` thay vì global
+
+**3e. useEffect (cleanup)**: Stop audio + disconnect nodes khi unmount
+
+**3f. JSX return**: ~250 dòng JSX, dịch sát spec HTML lines 121-480:
+- Overlay modal container `fixed inset-0 z-[100] bg-black/60 backdrop-blur-sm`
+- Bên trong: `flex flex-col` container với `h-[90vh] w-[90vw] max-w-[1400px]`
+- Header bar (logo, transport, preset select, LUFS)
+- Module chain strip (3 module cards + add slot, `oz-card-active` toggle)
+- Main workspace:
+  - Sub toolbar (Delta listen, IRC mode select, Learn Input Gain)
+  - `viewDynamicEq` (EQ canvas + 4-band knob panel, show khi `activeModule==='eq'`)
+  - `viewImager` (vectorscope canvas + 4-band sliders, show khi `activeModule==='imager'`)
+  - `viewMaximizer` (gain knob, upward comp, soft clip, transient knobs, show khi `activeModule==='maximizer'`)
+- Right sidebar I/O meters (in/out peak text, meter canvases, bypass/gain match/codec/dither buttons)
+- Close button (góc trên phải)
+
+### Task 4: Build & Verify
+```bash
+npm run build
+```
+Kiểm tra: mở app → menu → "Mastering Suite" → modal hiển thị, Play Reference Loop phát âm thanh, canvas vẽ, knobs kéo được.
+
+## Files Affected
+| File | Lines | Change |
+|------|-------|--------|
+| `app/templates/index.html` | +30 | Thêm CSS classes (oz-panel, oz-card, knob-dial, scrollbar) |
+| `app/static/js/app.jsx` | ~dòng 6690 + 7708 + 15585 + 18664 | Thêm MasteringModal component + state + menu item + render |
+
+## Skipped (PONYTALL)
+- Real M/S processing: phase 1 chỉ UI + vectorscope viz. Thêm actual M/S khi user upload file stereo thật.
+- Delta Listen / Gain Match / Codec / Dither: UI button renders, DSP stubbed. Thêm sau.
+- Drag-drop module reorder: spec define UX. Phase 1: fixed chain.
+- Preset save/load: UI dropdown + defaults. Backend integration sau.

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/admin.py

@@ -20,6 +20,12 @@ class UpdateUserRoleRequest(BaseModel):
     role: str # 'admin', 'standard', 'premium'
     is_active: Optional[bool] = True
 
+class CreateUserRequest(BaseModel):
+    username: str
+    email: str
+    password: str
+    role: Optional[str] = 'standard'
+
 @router.get("/users")
 async def list_users(admin: dict = Depends(require_admin)):
     conn = get_db_connection()
@@ -52,6 +58,29 @@ async def list_users(admin: dict = Depends(require_admin)):
         })
     return users
 
+@router.post("/users")
+async def create_user(req: CreateUserRequest, admin: dict = Depends(require_admin)):
+    import uuid, time
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    cursor.execute("SELECT id FROM users WHERE username = ? OR email = ?", (req.username, req.email))
+    if cursor.fetchone():
+        conn.close()
+        raise HTTPException(status_code=409, detail="Tên đăng nhập hoặc email đã tồn tại")
+    user_id = str(uuid.uuid4())
+    hashed = hash_password(req.password)
+    now = time.time()
+    cursor.execute("""
+    INSERT INTO users (id, username, email, hashed_password, role, must_change_password, created_at, is_active)
+    VALUES (?, ?, ?, ?, ?, 1, ?, 1)
+    """, (user_id, req.username, req.email, hashed, req.role, now))
+    cursor.execute("""
+    INSERT INTO user_quotas (user_id, storage_limit_mb, max_tracks) VALUES (?, 500, 16)
+    """, (user_id,))
+    conn.commit()
+    conn.close()
+    return {"message": f"Đã tạo người dùng '{req.username}' thành công", "user_id": user_id}
+
 @router.put("/users/{user_id}/role")
 async def update_user_role(user_id: str, req: UpdateUserRoleRequest, admin: dict = Depends(require_admin)):
     conn = get_db_connection()
@@ -81,7 +110,7 @@ async def delete_user(user_id: str, admin: dict = Depends(require_admin)):
     conn = get_db_connection()
     cursor = conn.cursor()
     cursor.execute("DELETE FROM users WHERE id = ?", (user_id,))
-    cursor.execute("DELETE FROM user_quotas WHERE id = ?", (user_id,))
+    cursor.execute("DELETE FROM user_quotas WHERE user_id = ?", (user_id,))
     cursor.execute("DELETE FROM projects WHERE user_id = ?", (user_id,))
     conn.commit()
     conn.close()

app/api/v1/ai_presets.py

@@ -0,0 +1,200 @@
+import json, os, time
+from fastapi import APIRouter, HTTPException, Header
+from pydantic import BaseModel
+from typing import Optional, List
+from app.core.auth import decode_token
+from app.config import settings
+
+router = APIRouter()
+
+DATA_FILE = os.path.join(settings.PROCESSED_DIR, "ai_presets.json")
+
+DEFAULT_PRESETS = [
+    {
+        "id": "preset_epic_orchestra_intro",
+        "name": "Epic Orchestra Intro (8 Bars)",
+        "keywords": ["epic orchestra", "epic orchestral", "hoành tráng", "nhạc phim epic"],
+        "category": "Orchestral / Film Score",
+        "default_bars": 8,
+        "default_bpm": 130,
+        "default_scale": "C Minor",
+        "system_instruction_template": "You are a professional film composer. Create a powerful, dramatic 8-bar orchestral intro. Keep the note density low (e.g. use mostly whole notes, half notes, or quarter notes) and do NOT generate dense 16th notes or complex drum rolls. This is critical to avoid output token limit timeouts. The required structure to return via the `generate_multitrack_midi` tool consists of 3 tracks: 1. Strings: plays smooth legato chord changes (one chord per 1 or 2 bars). 2. Brass Theme: plays a swelling simple melodic line in the C3-C5 range. 3. Epic Percussion: hits heavily on beats 1 and 3. Ensure the duration is precisely 8 bars (32 beats).",
+        "is_user_defined": False,
+        "is_favorite": False,
+        "created_at": "2026-07-23T16:00:00Z"
+    },
+    {
+        "id": "preset_pop_piano_chords",
+        "name": "Pop Piano Chords (4 Bars)",
+        "keywords": ["pop piano", "piano chords", "ballad piano", "hợp âm piano"],
+        "category": "Pop / Ballad",
+        "default_bars": 4,
+        "default_bpm": 90,
+        "default_scale": "C Major",
+        "system_instruction_template": "You are a professional Pop Piano player. Generate a beautiful 4-bar piano chord progression (e.g. C - G - Am - F) with pleasant chord voicing and simple accompaniment. Return the MIDI notes via `generate_multitrack_midi` function on a track named 'Pop Piano'. Keep notes simple, using mostly whole/half/quarter notes. Ensure the duration of the track is precisely 4 bars (16 beats).",
+        "is_user_defined": False,
+        "is_favorite": False,
+        "created_at": "2026-07-23T16:00:00Z"
+    },
+    {
+        "id": "preset_cyberpunk_synth",
+        "name": "Cyberpunk Synthwave (8 Bars)",
+        "keywords": ["cyberpunk synth", "synthwave", "cyberpunk", "futuristic synth"],
+        "category": "Electronic / Synthwave",
+        "default_bars": 8,
+        "default_bpm": 120,
+        "default_scale": "A Minor",
+        "system_instruction_template": "You are a Synthwave producer. Generate a driving 8-bar cyberpunk synth theme. Return MIDI notes via `generate_multitrack_midi` containing: 1. Synth Bass: eighth notes on pitch A1, C2, G1. 2. Synth Lead: simple melodic line in high register C4-E5. Keep notes clean and concise to ensure fast generation.",
+        "is_user_defined": False,
+        "is_favorite": False,
+        "created_at": "2026-07-23T16:00:00Z"
+    },
+    {
+        "id": "preset_rearrange_jazz_swing",
+        "name": "Jazz Swing Variation",
+        "keywords": ["jazz", "swing", "rearrange to jazz", "jazz improv"],
+        "category": "Rearrange / Variation",
+        "default_bars": 4,
+        "default_bpm": 120,
+        "default_scale": "C Major",
+        "system_instruction_template": "Rearrange the original melody into a rhythmic Jazz Swing style. Apply syncopation, 7th/9th chord extensions, and off-beat rhythmic feel.",
+        "is_user_defined": False,
+        "is_favorite": True,
+        "created_at": "2026-07-28T11:00:00Z"
+    },
+    {
+        "id": "preset_rearrange_synth_arpeggio",
+        "name": "80s Synthwave Arpeggiator",
+        "keywords": ["synthwave", "arpeggio", "arp", "16th variation", "80s synth"],
+        "category": "Rearrange / Variation",
+        "default_bars": 4,
+        "default_bpm": 120,
+        "default_scale": "C Minor",
+        "system_instruction_template": "Transform this sequence into a driving, shimmering 16th-note Arpeggio string in classic 80s Synthwave/Trance style.",
+        "is_user_defined": False,
+        "is_favorite": False,
+        "created_at": "2026-07-28T11:00:00Z"
+    },
+    {
+        "id": "preset_rearrange_harmonize",
+        "name": "Chords Harmonization (4-Note)",
+        "keywords": ["harmonize", "harmony", "add chord notes", "rich melody"],
+        "category": "Rearrange / Variation",
+        "default_bars": 4,
+        "default_bpm": 120,
+        "default_scale": "C Major",
+        "system_instruction_template": "Add harmonizing notes to create lush 4-note chord voicing extensions beneath the lead melody.",
+        "is_user_defined": False,
+        "is_favorite": False,
+        "created_at": "2026-07-28T11:00:00Z"
+    },
+    {
+        "id": "preset_rearrange_cinematic_strings",
+        "name": "Cinematic Strings Staccato",
+        "keywords": ["cinematic", "strings", "staccato", "staccato strings"],
+        "category": "Rearrange / Variation",
+        "default_bars": 4,
+        "default_bpm": 120,
+        "default_scale": "C Minor",
+        "system_instruction_template": "Rearrange the original line into a dramatic, driving Staccato rhythm for a Strings Ensemble.",
+        "is_user_defined": False,
+        "is_favorite": True,
+        "created_at": "2026-07-28T11:00:00Z"
+    }
+]
+
+
+class AIPresetSchema(BaseModel):
+    id: str
+    name: str
+    keywords: List[str]
+    category: str = "General"
+    default_bars: int = 8
+    default_bpm: int = 120
+    default_scale: str = "C Major"
+    system_instruction_template: str
+    is_user_defined: bool = True
+    is_favorite: bool = False
+    created_at: Optional[str] = None
+
+
+def _load_data():
+    if not os.path.exists(DATA_FILE):
+        return {"user_presets": {}}
+    try:
+        with open(DATA_FILE, "r") as f:
+            return json.load(f)
+    except Exception:
+        return {"user_presets": {}}
+
+
+def _save_data(user_presets):
+    os.makedirs(os.path.dirname(DATA_FILE), exist_ok=True)
+    with open(DATA_FILE, "w") as f:
+        json.dump({"user_presets": user_presets}, f, indent=2)
+
+
+def _get_user_id(authorization):
+    if not authorization or not authorization.startswith("Bearer "):
+        return "anonymous"
+    token = authorization.split(" ")[1]
+    payload = decode_token(token)
+    if not payload:
+        return "anonymous"
+    return payload.get("user_id", "anonymous")
+
+
+@router.get("/presets")
+async def list_presets(authorization: Optional[str] = Header(None)):
+    uid = _get_user_id(authorization)
+    data = _load_data()
+    user_presets = data.get("user_presets", {}).get(uid, [])
+    merged = DEFAULT_PRESETS + user_presets
+    return {"success": True, "presets": merged}
+
+
+@router.post("/presets")
+async def save_preset(req: AIPresetSchema, authorization: Optional[str] = Header(None)):
+    uid = _get_user_id(authorization)
+    if uid == "anonymous":
+        raise HTTPException(status_code=401, detail="Authentication required to save presets")
+
+    data = _load_data()
+    user_presets = data.get("user_presets", {}).get(uid, [])
+
+    if not req.created_at:
+        req.created_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+    existing_idx = next((i for i, p in enumerate(user_presets) if p["id"] == req.id), None)
+    preset_dict = req.model_dump()
+
+    if existing_idx is not None:
+        user_presets[existing_idx] = preset_dict
+    else:
+        user_presets.append(preset_dict)
+
+    if "user_presets" not in data:
+        data["user_presets"] = {}
+    data["user_presets"][uid] = user_presets
+    _save_data(data["user_presets"])
+    return {"success": True, "preset": preset_dict}
+
+
+@router.delete("/presets/{preset_id}")
+async def delete_preset(preset_id: str, authorization: Optional[str] = Header(None)):
+    uid = _get_user_id(authorization)
+    if uid == "anonymous":
+        raise HTTPException(status_code=401, detail="Authentication required to delete presets")
+
+    data = _load_data()
+    user_presets = data.get("user_presets", {}).get(uid, [])
+    filtered = [p for p in user_presets if p["id"] != preset_id]
+
+    if len(filtered) == len(user_presets):
+        raise HTTPException(status_code=404, detail="Preset not found")
+
+    if "user_presets" not in data:
+        data["user_presets"] = {}
+    data["user_presets"][uid] = filtered
+    _save_data(data["user_presets"])
+    return {"success": True, "message": "Preset deleted"}

app/api/v1/ai_proxy.py

@@ -1,7 +1,16 @@
+import asyncio
+import ipaddress
+import json
+import socket
+from urllib.parse import urlparse
+
 import httpx
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel
-from typing import Optional, Any, Dict, List
+from typing import Any, Dict
+
+from app.api.v1.auth import get_current_user
+from app.api.v1.user_config import _load_ai_configs, _get_default_providers
 
 router = APIRouter()
 
@@ -10,17 +19,108 @@ class ProxyRequest(BaseModel):
     headers: Dict[str, str] = {}
     body: Dict[str, Any] = {}
 
-import json
+
+# Ranges that are never legitimate AI endpoints: cloud metadata + this host.
+_BLOCKED_NETWORKS = [
+    ipaddress.ip_network("169.254.0.0/16"),   # link-local / cloud metadata
+    ipaddress.ip_network("0.0.0.0/8"),
+]
+# Private ranges: only reachable when the target host is one the user has
+# explicitly configured as an AI provider (e.g. local Ollama/LM Studio).
+_PRIVATE_NETWORKS = [
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("172.16.0.0/12"),
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("::1/128"),
+    ipaddress.ip_network("fc00::/7"),          # ULA
+]
+
+_LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1", "0.0.0.0"}
+
+
+def _configured_ai_hosts(user_id: str) -> set:
+    """Hosts the user has configured as AI providers (from saved config + defaults)."""
+    hosts = set()
+    configs = _load_ai_configs()
+    providers = configs.get(user_id) or _get_default_providers()
+    for p in providers:
+        base = (p.get("api_base_url") or "").strip()
+        if not base:
+            continue
+        try:
+            host = urlparse(base).hostname
+            if host:
+                hosts.add(host.lower())
+        except Exception:
+            continue
+    return hosts
+
+
+async def _resolve_host_ips(hostname: str):
+    """Resolve hostname to IPs (non-blocking). Returns list of ipaddress objects."""
+    loop = asyncio.get_event_loop()
+    try:
+        infos = await loop.run_in_executor(None, socket.getaddrinfo, hostname, None)
+        ips = []
+        for info in infos:
+            try:
+                ips.append(ipaddress.ip_address(info[4][0]))
+            except ValueError:
+                continue
+        return ips
+    except Exception:
+        return []
+
+
+async def _validate_target_url(url: str, user_id: str):
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise HTTPException(status_code=400, detail="URL chỉ hỗ trợ giao thức http/https")
+    if parsed.username or parsed.password:
+        raise HTTPException(status_code=400, detail="URL không được chứa thông tin đăng nhập")
+    hostname = (parsed.hostname or "").lower()
+    if not hostname:
+        raise HTTPException(status_code=400, detail="URL không hợp lệ")
+
+    allowed_hosts = _configured_ai_hosts(user_id)
+
+    # Hostname-level fast path for loopback hosts
+    if hostname in _LOOPBACK_HOSTS:
+        if hostname in allowed_hosts:
+            return
+        raise HTTPException(status_code=403, detail="Target nội bộ không nằm trong danh sách AI provider đã cấu hình")
+
+    # Try direct IP parse (hostname may itself be an IP)
+    try:
+        ip = ipaddress.ip_address(hostname)
+        ips = [ip]
+    except ValueError:
+        ips = await _resolve_host_ips(hostname)
+
+    if not ips:
+        raise HTTPException(status_code=502, detail="Không phân giải được hostname")
+
+    for ip in ips:
+        if any(ip in net for net in _BLOCKED_NETWORKS):
+            raise HTTPException(status_code=403, detail="Target bị chặn (metadata/link-local không được phép)")
+        if any(ip in net for net in _PRIVATE_NETWORKS):
+            if hostname in allowed_hosts:
+                continue
+            raise HTTPException(status_code=403, detail="Target IP nội bộ không nằm trong danh sách AI provider đã cấu hình")
+
 
 @router.post("/proxy")
-async def proxy_llm(req: ProxyRequest):
+async def proxy_llm(req: ProxyRequest, current_user: dict = Depends(get_current_user)):
+    await _validate_target_url(req.url, current_user["user_id"])
+    # Never forward the app's own auth token upstream.
+    headers = {
+        k: v for k, v in req.headers.items()
+        if k.lower() not in ("host", "origin", "referer", "x-auth-token")
+    }
     try:
-        async with httpx.AsyncClient(timeout=180.0) as client:
-            resp = await client.post(
-                req.url,
-                headers={k: v for k, v in req.headers.items() if k.lower() not in ('host', 'origin', 'referer')},
-                json=req.body
-            )
+        async with httpx.AsyncClient(timeout=180.0, follow_redirects=False) as client:
+            resp = await client.post(req.url, headers=headers, json=req.body)
             raw = resp.text
             try:
                 return resp.json()
@@ -36,5 +136,7 @@ async def proxy_llm(req: ProxyRequest):
         if 'localhost' in req.url or '127.0.0.1' in req.url:
             msg += "\nNếu app chạy trong Docker, localhost trỏ vào container, không ra host.\nHãy thay localhost bằng host.docker.internal hoặc IP bridge Docker (172.17.0.1)."
         raise HTTPException(status_code=502, detail=msg)
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))

app/api/v1/audio.py

@@ -8,12 +8,32 @@ from pydantic import BaseModel
 from typing import Optional, List
 import json
 from app.config import settings
-from app.api.v1.auth import get_current_user
+from app.api.v1.auth import get_current_user, enforce_password_changed
 from app.api.v1.projects import get_optional_user
 from app.models.user import get_db_connection
 
 router = APIRouter()
 
+MAX_AUDIO_UPLOAD_BYTES = 1024 * 1024 * 1024  # 1 GB
+
+def _safe_file_id(file_id: str) -> str:
+    """Strip any path components from a client-supplied file id."""
+    if not file_id:
+        return ""
+    return os.path.basename(file_id.replace("\\", "/"))
+
+def _resolve_storage_path(file_id: str) -> str:
+    """Return the existing file path (processed first, then uploads) for a
+    sanitized file id, or '' when not found."""
+    fid = _safe_file_id(file_id)
+    if not fid:
+        return ""
+    for d in (settings.PROCESSED_DIR, settings.UPLOADS_DIR):
+        p = os.path.join(d, fid)
+        if os.path.isfile(p):
+            return p
+    return ""
+
 class EditRequest(BaseModel):
     file_id: str
     cut_start_ms: Optional[float] = None
@@ -58,16 +78,32 @@ class PythonToolRequest(BaseModel):
 
 @router.post("/upload")
 async def upload_audio(file: UploadFile = File(...), current_user: Optional[dict] = Depends(get_optional_user)):
+    if current_user:
+        enforce_password_changed(current_user)
     user_id = current_user["user_id"] if current_user else "anonymous"
-    ext = os.path.splitext(file.filename)[1]
+    ext = os.path.splitext(file.filename or "")[1]
     if not ext:
         ext = ".wav"
     file_id = f"user_{user_id}_{uuid.uuid4()}{ext}"
     file_path = os.path.join(settings.UPLOADS_DIR, file_id)
     
+    # Stream upload in chunks with a hard size cap (avoids loading a multi-GB
+    # WAV into RAM and bounds disk usage).
     with open(file_path, "wb") as f:
-        content = await file.read()
-        f.write(content)
+        size = 0
+        while True:
+            chunk = await file.read(1024 * 1024)
+            if not chunk:
+                break
+            size += len(chunk)
+            if size > MAX_AUDIO_UPLOAD_BYTES:
+                f.close()
+                try:
+                    os.remove(file_path)
+                except OSError:
+                    pass
+                raise HTTPException(status_code=413, detail="File âm thanh quá lớn (giới hạn 1GB)")
+            f.write(chunk)
     
     # Save original filename as sidecar metadata
     import json
@@ -90,15 +126,12 @@ async def upload_audio(file: UploadFile = File(...), current_user: Optional[dict
 
 @router.post("/edit")
 async def edit_audio(req: EditRequest):
-    upload_path = os.path.join(settings.UPLOADS_DIR, req.file_id)
-    processed_path = os.path.join(settings.PROCESSED_DIR, req.file_id)
-    
     # Use uploaded file if it exists, or look in processed if it was already edited
-    if not os.path.exists(upload_path) and not os.path.exists(processed_path):
+    if not _resolve_storage_path(req.file_id):
         raise HTTPException(status_code=404, detail="File not found")
         
     from app.tasks.worker import edit_audio_task
-    task = edit_audio_task.delay(req.dict())
+    task = edit_audio_task.delay(req.model_dump())
     
     return {
         "task_id": task.id
@@ -106,15 +139,10 @@ async def edit_audio(req: EditRequest):
 
 @router.get("/download/{file_id}")
 async def download_audio(file_id: str):
-    processed_path = os.path.join(settings.PROCESSED_DIR, file_id)
-    upload_path = os.path.join(settings.UPLOADS_DIR, file_id)
-    
-    if os.path.exists(processed_path):
-        return FileResponse(processed_path, media_type="audio/wav", filename=file_id)
-    elif os.path.exists(upload_path):
-        return FileResponse(upload_path, media_type="audio/wav", filename=file_id)
-    
-    raise HTTPException(status_code=404, detail="File not found")
+    path = _resolve_storage_path(file_id)
+    if not path:
+        raise HTTPException(status_code=404, detail="File not found")
+    return FileResponse(path, media_type="audio/wav", filename=os.path.basename(path))
 
 @router.get("/waveform/{file_id}")
 async def get_waveform(file_id: str, num_peaks: int = Query(default=800, ge=50, le=4000)):
@@ -122,14 +150,8 @@ async def get_waveform(file_id: str, num_peaks: int = Query(default=800, ge=50,
     API endpoint vẽ Peak Waveform đồng bộ (Week 2).
     Trả về dữ liệu peak waveform cho hiển thị đồ thị sóng âm trên Frontend.
     """
-    upload_path = os.path.join(settings.UPLOADS_DIR, file_id)
-    processed_path = os.path.join(settings.PROCESSED_DIR, file_id)
-    
-    if os.path.exists(processed_path):
-        file_path = processed_path
-    elif os.path.exists(upload_path):
-        file_path = upload_path
-    else:
+    file_path = _resolve_storage_path(file_id)
+    if not file_path:
         raise HTTPException(status_code=404, detail="File not found")
     
     from app.core.dsp_utils import generate_peak_waveform
@@ -140,14 +162,8 @@ async def get_waveform_rms(file_id: str, num_points: int = Query(default=800, ge
     """
     API endpoint vẽ RMS Waveform (mượt hơn peak).
     """
-    upload_path = os.path.join(settings.UPLOADS_DIR, file_id)
-    processed_path = os.path.join(settings.PROCESSED_DIR, file_id)
-    
-    if os.path.exists(processed_path):
-        file_path = processed_path
-    elif os.path.exists(upload_path):
-        file_path = upload_path
-    else:
+    file_path = _resolve_storage_path(file_id)
+    if not file_path:
         raise HTTPException(status_code=404, detail="File not found")
     
     from app.core.dsp_utils import generate_rms_waveform
@@ -159,26 +175,20 @@ async def analyze_audio_with_ai(req: AIAnalysisRequest):
     API endpoint phân tích cấu trúc khuôn nhạc bằng AI (Week 4).
     Gọi OpenAI Compatible API (DeepSeek/Ollama) để phân đoạn bố cục.
     """
-    upload_path = os.path.join(settings.UPLOADS_DIR, req.file_id)
-    processed_path = os.path.join(settings.PROCESSED_DIR, req.file_id)
-    
-    if os.path.exists(processed_path):
-        file_path = processed_path
-    elif os.path.exists(upload_path):
-        file_path = upload_path
-    else:
+    file_path = _resolve_storage_path(req.file_id)
+    if not file_path:
         raise HTTPException(status_code=404, detail="File not found")
     
     from app.tasks.worker import analyze_ai_task
     task = analyze_ai_task.delay(
-        file_id=req.file_id,
+        file_id=_safe_file_id(req.file_id),
         api_base_url=req.api_base_url,
         model=req.model
     )
     
     return {
         "task_id": task.id,
-        "file_id": req.file_id
+        "file_id": _safe_file_id(req.file_id)
     }
 
 @router.post("/export")
@@ -186,19 +196,13 @@ async def export_audio(req: ExportRequest):
     """
     API endpoint xuất tệp âm thanh sang nhiều định dạng (WAV/MP3/OGG).
     """
-    upload_path = os.path.join(settings.UPLOADS_DIR, req.file_id)
-    processed_path = os.path.join(settings.PROCESSED_DIR, req.file_id)
-    
-    if os.path.exists(processed_path):
-        source_path = processed_path
-    elif os.path.exists(upload_path):
-        source_path = upload_path
-    else:
+    source_path = _resolve_storage_path(req.file_id)
+    if not source_path:
         raise HTTPException(status_code=404, detail="File not found")
     
     from app.tasks.worker import export_audio_task
     task = export_audio_task.delay(
-        file_id=req.file_id,
+        file_id=_safe_file_id(req.file_id),
         format=req.format,
         sample_rate=req.sample_rate,
         bit_depth=req.bit_depth
@@ -206,29 +210,24 @@ async def export_audio(req: ExportRequest):
     
     return {
         "task_id": task.id,
-        "file_id": req.file_id
+        "file_id": _safe_file_id(req.file_id)
     }
 
 @router.post("/ai-scan")
-async def ai_scan_audio(req: AIScanRequest):
+async def ai_scan_audio(req: AIScanRequest, current_user: Optional[dict] = Depends(get_optional_user)):
     """
     17_AI_SCAN.md Feature 1: AI Loop Scan & Automated Marker Labeling.
     Uses AIDSPEngine to find optimal recurring loop region with zero-crossing alignment.
     """
+    if current_user:
+        enforce_password_changed(current_user)
     from app.core.ai_dsp_engine import AIDSPEngine
     import soundfile as sf
     import numpy as np
     
-    file_path = None
-    if req.file_id:
-        upload_path = os.path.join(settings.UPLOADS_DIR, req.file_id)
-        processed_path = os.path.join(settings.PROCESSED_DIR, req.file_id)
-        if os.path.exists(processed_path):
-            file_path = processed_path
-        elif os.path.exists(upload_path):
-            file_path = upload_path
+    file_path = _resolve_storage_path(req.file_id) if req.file_id else ""
 
-    if file_path and os.path.exists(file_path):
+    if file_path:
         data, sr = sf.read(file_path)
         if data.ndim > 1:
             data = data.T
@@ -252,6 +251,8 @@ async def ai_cut_audio(req: AICutRequest, current_user: Optional[dict] = Depends
     Executes raw binary sample slice at exact zero-crossing coordinates.
     """
     user_id = current_user["user_id"] if current_user else "anonymous"
+    if current_user:
+        enforce_password_changed(current_user)
     from app.core.ai_dsp_engine import AIDSPEngine
     import soundfile as sf
     import numpy as np
@@ -259,16 +260,9 @@ async def ai_cut_audio(req: AICutRequest, current_user: Optional[dict] = Depends
     output_file_id = f"user_{user_id}_ai_cut_{uuid.uuid4().hex[:8]}.wav"
     out_path = os.path.join(settings.PROCESSED_DIR, output_file_id)
     
-    file_path = None
-    if req.file_id:
-        upload_path = os.path.join(settings.UPLOADS_DIR, req.file_id)
-        processed_path = os.path.join(settings.PROCESSED_DIR, req.file_id)
-        if os.path.exists(processed_path):
-            file_path = processed_path
-        elif os.path.exists(upload_path):
-            file_path = upload_path
+    file_path = _resolve_storage_path(req.file_id) if req.file_id else ""
 
-    if file_path and os.path.exists(file_path):
+    if file_path:
         data, sr = sf.read(file_path)
         if data.ndim > 1:
             data = data.T
@@ -295,6 +289,8 @@ async def run_python_dsp_tool(req: PythonToolRequest, current_user: Optional[dic
     Handles normalize peak, invert phase, swap channels, zero-crossing align, and synth wave generation.
     """
     user_id = current_user["user_id"] if current_user else "anonymous"
+    if current_user:
+        enforce_password_changed(current_user)
     from app.core.python_tools_engine import PythonToolsEngine
     from app.core.ai_dsp_engine import AIDSPEngine
     import soundfile as sf

app/api/v1/auth.py

@@ -1,10 +1,15 @@
 import uuid
 import time
-from fastapi import APIRouter, HTTPException, Header, Depends
+import threading
+from fastapi import APIRouter, HTTPException, Header, Depends, Request, Response
+from fastapi.responses import JSONResponse
 from pydantic import BaseModel, EmailStr
 from typing import Optional
 from app.models.user import get_db_connection
-from app.core.auth import hash_password, verify_password, create_token, decode_token, seed_admin
+from app.core.auth import (
+    hash_password, verify_password, create_token, decode_token, seed_admin,
+    COOKIE_NAME, X_AUTH_HEADER,
+)
 
 router = APIRouter()
 
@@ -21,10 +26,49 @@ class ChangePasswordRequest(BaseModel):
     old_password: str
     new_password: str
 
-def get_current_user(authorization: Optional[str] = Header(None)):
-    if not authorization or not authorization.startswith("Bearer "):
+# ── Brute-force guard: in-memory per-IP failed-login limiter ──
+_LOGIN_FAILURES = {}          # ip -> [timestamps]
+_LOGIN_LOCK = threading.Lock()
+MAX_LOGIN_ATTEMPTS = 10
+LOGIN_WINDOW_SEC = 900        # 15 min
+LOGIN_BLOCK_SEC = 900
+
+def _check_login_ratelimit(ip: str):
+    now = time.time()
+    with _LOGIN_LOCK:
+        stamps = [t for t in _LOGIN_FAILURES.get(ip, []) if now - t < LOGIN_WINDOW_SEC]
+        if len(stamps) >= MAX_LOGIN_ATTEMPTS:
+            raise HTTPException(status_code=429, detail="Quá nhiều lần đăng nhập thất bại. Vui lòng thử lại sau 15 phút.")
+        _LOGIN_FAILURES[ip] = stamps
+
+def _record_login_failure(ip: str):
+    now = time.time()
+    with _LOGIN_LOCK:
+        stamps = _LOGIN_FAILURES.setdefault(ip, [])
+        stamps.append(now)
+        _LOGIN_FAILURES[ip] = [t for t in stamps if now - t < LOGIN_WINDOW_SEC]
+
+def _record_login_success(ip: str):
+    with _LOGIN_LOCK:
+        _LOGIN_FAILURES.pop(ip, None)
+
+def _set_auth_cookie(response: Response, token: str):
+    response.set_cookie(
+        COOKIE_NAME, token,
+        max_age=7 * 24 * 3600, httponly=True, samesite="lax",
+        # path="/" (default); secure flag set by proxy when behind TLS
+    )
+
+def get_current_user(request: Request, authorization: Optional[str] = Header(None), x_auth_token: Optional[str] = Header(None)):
+    token = None
+    if authorization and authorization.startswith("Bearer "):
+        token = authorization.split(" ")[1]
+    elif x_auth_token:
+        token = x_auth_token
+    elif request.cookies.get(COOKIE_NAME):
+        token = request.cookies.get(COOKIE_NAME)
+    if not token:
         raise HTTPException(status_code=401, detail="Thiếu Token xác thực hoặc Token không hợp lệ")
-    token = authorization.split(" ")[1]
     payload = decode_token(token)
     if not payload:
         raise HTTPException(status_code=401, detail="Token đã hết hạn hoặc không hợp lệ")
@@ -39,7 +83,10 @@ def enforce_password_changed(user: dict):
         )
 
 @router.post("/login")
-async def login(req: LoginRequest):
+async def login(req: LoginRequest, request: Request):
+    client_ip = request.client.host if request.client else "unknown"
+    _check_login_ratelimit(client_ip)
+
     conn = get_db_connection()
     cursor = conn.cursor()
     
@@ -65,14 +112,17 @@ async def login(req: LoginRequest):
     conn.close()
     
     if not user or not user["is_active"]:
+        _record_login_failure(client_ip)
         raise HTTPException(status_code=400, detail="Tài khoản hoặc mật khẩu không chính xác")
         
     if not verify_password(password, user["hashed_password"]):
+        _record_login_failure(client_ip)
         raise HTTPException(status_code=400, detail="Tài khoản hoặc mật khẩu không chính xác")
         
     token = create_token(user["id"], user["username"], user["role"], user["must_change_password"])
-    
-    return {
+    _record_login_success(client_ip)
+
+    resp = JSONResponse({
         "access_token": token,
         "user": {
             "id": user["id"],
@@ -81,13 +131,24 @@ async def login(req: LoginRequest):
             "role": user["role"],
             "must_change_password": bool(user["must_change_password"])
         }
-    }
+    })
+    _set_auth_cookie(resp, token)
+    return resp
+
+def _validate_password_strength(password: str):
+    """Minimal strength policy: >= 8 chars and not trivially common."""
+    if len(password) < 8:
+        raise HTTPException(status_code=400, detail="Mật khẩu phải có ít nhất 8 ký tự")
+    lowered = password.lower()
+    if lowered in ("admin123", "password", "12345678", "123456789", "qwerty123"):
+        raise HTTPException(status_code=400, detail="Mật khẩu quá dễ đoán, vui lòng chọn mật khẩu khác")
 
 @router.post("/register")
-async def register(req: RegisterRequest):
+async def register(req: RegisterRequest, request: Request):
     username = req.username.strip()
     email = req.email.strip()
     password = req.password.strip()
+    _validate_password_strength(password)
     
     conn = get_db_connection()
     cursor = conn.cursor()
@@ -115,7 +176,7 @@ async def register(req: RegisterRequest):
     conn.close()
     
     token = create_token(user_id, username, "standard", False)
-    return {
+    resp = JSONResponse({
         "access_token": token,
         "user": {
             "id": user_id,
@@ -124,7 +185,9 @@ async def register(req: RegisterRequest):
             "role": "standard",
             "must_change_password": False
         }
-    }
+    })
+    _set_auth_cookie(resp, token)
+    return resp
 
 @router.post("/change-password")
 async def change_password(req: ChangePasswordRequest, current_user: dict = Depends(get_current_user)):
@@ -153,10 +216,12 @@ async def change_password(req: ChangePasswordRequest, current_user: dict = Depen
     conn.close()
     
     new_token = create_token(updated_user["id"], updated_user["username"], updated_user["role"], False)
-    return {
+    resp = JSONResponse({
         "message": "Đổi mật khẩu thành công!",
         "access_token": new_token
-    }
+    })
+    _set_auth_cookie(resp, new_token)
+    return resp
 
 @router.get("/profile")
 async def get_profile(current_user: dict = Depends(get_current_user)):
@@ -194,3 +259,32 @@ async def get_profile(current_user: dict = Depends(get_current_user)):
             "max_tracks": row["max_tracks"] or 16
         }
     }
+
+
+@router.get("/first-time")
+async def auth_first_time():
+    # "Lần đăng nhập đầu" = tài khoản admin vẫn dùng mật khẩu MẶC ĐỊNH
+    # (chưa từng đổi). Sau khi đổi lần đầu → first_time = false → UI xóa
+    # gợi ý username/mật khẩu (Tùy chọn - Admin có thể bỏ trống, lần đầu:
+    # admin123, nút Điền nhanh).
+    try:
+        conn = get_db_connection()
+        try:
+            cur = conn.cursor()
+            cur.execute(
+                "SELECT id, hashed_password, must_change_password FROM users "
+                "WHERE LOWER(role) = 'admin' ORDER BY created_at ASC LIMIT 1"
+            )
+            row = cur.fetchone()
+        finally:
+            conn.close()
+        if not row:
+            return {"first_time": True}
+        still_default = False
+        try:
+            still_default = verify_password("admin123", row["hashed_password"])
+        except Exception:
+            still_default = False
+        return {"first_time": bool(row["must_change_password"]) and still_default}
+    except Exception:
+        return {"first_time": True}

app/api/v1/media.py

@@ -0,0 +1,160 @@
+import os
+import platform
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi.responses import FileResponse
+
+from app.api.v1.auth import get_current_user
+
+router = APIRouter()
+
+MEDIA_EXTS = {
+    ".wav", ".mp3", ".ogg", ".flac", ".aiff", ".aif", ".m4a", ".aac", ".opus",
+    ".mid", ".midi"
+}
+
+AUDIO_EXTS = {".wav", ".mp3", ".ogg", ".flac", ".aiff", ".aif", ".m4a", ".aac", ".opus"}
+MIDI_EXTS = {".mid", ".midi"}
+
+
+def _safe_path(path: str) -> str:
+    if not path:
+        raise HTTPException(status_code=400, detail="Thiếu path")
+    if "\x00" in path:
+        raise HTTPException(status_code=400, detail="Path không hợp lệ")
+    return os.path.normpath(path)
+
+
+REAL_FS_TYPES = {
+    "ext2", "ext3", "ext4", "xfs", "btrfs", "jfs", "reiserfs",
+    "ntfs", "ntfs3", "vfat", "exfat", "fat", "hfs", "hfsplus", "apfs",
+    "zfs", "f2fs", "iso9660", "udf", "nfs", "nfs4", "cifs", "smb3", "fuseblk",
+}
+
+PSEUDO_FS_TYPES = {
+    "proc", "sysfs", "devpts", "tmpfs", "devtmpfs", "overlay", "squashfs",
+    "cgroup", "cgroup2", "pstore", "securityfs", "debugfs", "tracefs",
+    "configfs", "fusectl", "hugetlbfs", "mqueue", "binfmt_misc", "nsfs",
+    "autofs", "ramfs", "efivarfs", "rpc_pipefs", "fuse", "fusefs",
+}
+
+
+@router.get("/computer")
+async def list_computer_roots(current_user: dict = Depends(get_current_user)):
+    """Liệt kê các ổ đĩa / mount point thật của máy (My Computer)."""
+    system = platform.system()
+    roots = []
+    if system == "Windows":
+        import string
+        for drive in string.ascii_uppercase:
+            root = drive + ":\\"
+            try:
+                if os.path.exists(root):
+                    roots.append({"path": root, "name": drive + ":", "is_dir": True})
+            except OSError:
+                continue
+    else:
+        # Unix/Linux/macOS: chỉ liệt kê filesystem thật, bỏ pseudo/docker/systemd mounts
+        seen = set()
+        try:
+            with open("/proc/mounts", "r") as f:
+                for line in f:
+                    parts = line.split()
+                    if len(parts) < 3:
+                        continue
+                    device, mount, fstype = parts[0], parts[1], parts[2]
+                    if fstype in PSEUDO_FS_TYPES:
+                        continue
+                    if fstype not in REAL_FS_TYPES:
+                        # giữ mount point root "/" nếu không thuộc pseudo
+                        if mount != "/":
+                            continue
+                    if mount in seen:
+                        continue
+                    seen.add(mount)
+                    # lọc mount point rác kiểu /run/credentials/...
+                    if mount.startswith("/run/") or mount.startswith("/var/lib/docker"):
+                        continue
+                    try:
+                        if os.path.isdir(mount):
+                            label = mount if mount != "/" else "Root (/)"
+                            roots.append({"path": mount, "name": label, "is_dir": True})
+                    except OSError:
+                        pass
+        except OSError:
+            pass
+        # macOS fallback: liệt kê /Volumes
+        if system == "Darwin":
+            try:
+                for name in sorted(os.listdir("/Volumes")):
+                    full = os.path.join("/Volumes", name)
+                    if os.path.isdir(full):
+                        roots.append({"path": full, "name": name, "is_dir": True})
+            except OSError:
+                pass
+        if not roots:
+            roots = [{"path": "/", "name": "Root (/)", "is_dir": True}]
+    return {"system": system, "roots": roots}
+
+
+@router.get("/browse")
+async def browse_directory(path: str = Query(...), current_user: dict = Depends(get_current_user)):
+    """Liệt kê nội dung một thư mục trên máy: thư mục con + file audio/MIDI."""
+    resolved = _safe_path(path)
+    if not os.path.isdir(resolved):
+        raise HTTPException(status_code=404, detail="Không tìm thấy thư mục")
+
+    dirs, files = [], []
+    try:
+        entries = os.listdir(resolved)
+    except OSError as e:
+        raise HTTPException(status_code=403, detail=f"Không thể đọc thư mục: {e}")
+
+    for name in entries:
+        if name.startswith("."):
+            continue
+        full = os.path.join(resolved, name)
+        try:
+            if os.path.isdir(full):
+                dirs.append({"name": name, "path": full, "is_dir": True})
+            else:
+                ext = os.path.splitext(name)[1].lower()
+                try:
+                    size = os.path.getsize(full)
+                except OSError:
+                    size = 0
+                kind = "midi" if ext in MIDI_EXTS else ("audio" if ext in AUDIO_EXTS else "other")
+                files.append({
+                    "name": name,
+                    "path": full,
+                    "is_dir": False,
+                    "size_mb": round(size / (1024 * 1024), 2),
+                    "ext": ext,
+                    "kind": kind
+                })
+        except OSError:
+            continue
+
+    dirs.sort(key=lambda d: d["name"].lower())
+    files.sort(key=lambda f: f["name"].lower())
+    parent = os.path.dirname(resolved)
+    return {
+        "path": resolved,
+        "parent": parent if parent != resolved else None,
+        "dirs": dirs,
+        "files": files
+    }
+
+
+@router.get("/file")
+async def serve_local_file(path: str = Query(...), current_user: dict = Depends(get_current_user)):
+    """Phục vụ file audio/MIDI cục bộ để preview."""
+    resolved = _safe_path(path)
+    if not os.path.isfile(resolved):
+        raise HTTPException(status_code=404, detail="Không tìm thấy file")
+    ext = os.path.splitext(resolved)[1].lower()
+    if ext not in MEDIA_EXTS:
+        raise HTTPException(status_code=403, detail="Loại file không được hỗ trợ preview")
+    media_type = "audio/wav" if ext in AUDIO_EXTS else "audio/midi"
+    return FileResponse(resolved, media_type=media_type, filename=os.path.basename(resolved))

app/api/v1/multitrack.py

@@ -54,7 +54,7 @@ async def mix_multitrack_session(req: MultitrackSessionRequest):
     
     # Gửi task xuống Celery Worker
     from app.tasks.worker import mix_multitrack_task
-    task = mix_multitrack_task.delay(req.dict())
+    task = mix_multitrack_task.delay(req.model_dump())
     
     return {
         "task_id": task.id,
@@ -69,7 +69,7 @@ async def process_session(req: MultitrackSessionRequest):
     Xử lý từng clip, sau đó hòa âm tất cả tracks lại với nhau.
     """
     from app.tasks.worker import process_multitrack_session_task
-    task = process_multitrack_session_task.delay(req.dict())
+    task = process_multitrack_session_task.delay(req.model_dump())
     
     return {
         "task_id": task.id,

app/api/v1/plugins.py

@@ -1,17 +1,39 @@
 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.api.v1.auth import get_current_user
+from app.core.soundfont_inspector import SoundFontInspector
+from app.core.soundfont_converter import SoundFontConverter
+from app.core.soundfont_scanner import SoundFontAutoScanner
+from app.api.v1.auth import get_current_user, enforce_password_changed
 
 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
+_scanner = 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
+
+def get_scanner():
+    global _scanner
+    if _scanner is None:
+        _scanner = SoundFontAutoScanner(system_sf_dir=SYSTEM_SF_DIR, upload_sf_dir=UPLOAD_SF_DIR)
+        _scanner.scan_once()
+    return _scanner
+
 
 @router.get("/available")
 async def list_plugins(current_user: dict = Depends(get_current_user)):
@@ -35,6 +57,15 @@ async def list_default_soundfonts():
     return result
 
 
+@router.get("/soundfonts/catalog")
+async def soundfont_catalog(current_user: dict = Depends(get_current_user)):
+    scanner = get_scanner()
+    full_catalog = scanner.get_catalog()
+    inspector = get_inspector()
+    condensed_catalog = inspector.get_condensed_catalog_summary(full_catalog)
+    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,13 +76,26 @@ 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)
 ):
+    enforce_password_changed(current_user)
     if not (file.filename and (file.filename.endswith(".sf2") or file.filename.endswith(".sf3"))):
         raise HTTPException(status_code=400, detail="Only .sf2 / .sf3 files are allowed")
 
-    contents = await file.read()
-    if not PluginManager.validate_sf2_header(contents):
+    # Stream upload in chunks with a hard size cap (SGM-class fonts can exceed
+    # 500MB; reading the whole body into RAM would OOM the server).
+    MAX_SF_UPLOAD_BYTES = 2 * 1024 * 1024 * 1024  # 2 GB
+    contents = bytearray()
+    while True:
+        chunk = await file.read(1024 * 1024)
+        if not chunk:
+            break
+        contents.extend(chunk)
+        if len(contents) > MAX_SF_UPLOAD_BYTES:
+            raise HTTPException(status_code=413, detail="SoundFont quá lớn (giới hạn 2GB)")
+
+    if not PluginManager.validate_sf2_header(bytes(contents[:4096])):
         raise HTTPException(status_code=400, detail="Invalid SoundFont file: missing RIFF/sfbk header")
 
     file_ext = os.path.splitext(file.filename)[1]
@@ -69,6 +113,11 @@ async def upload_soundfont(
         import json
         json.dump({"original_name": file.filename, "uuid": file_uuid, "file": file_id}, f)
 
+    scanner = get_scanner()
+    if background_tasks:
+        background_tasks.add_task(scanner.scan_once)
+    else:
+        scanner.scan_once()
     return {"id": file_id, "name": file.filename, "path": dest_path, "size_bytes": len(contents)}
 
 
@@ -76,14 +125,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 +144,46 @@ 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")
+    get_scanner().scan_once()
     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
+    # Cũng tìm trong static/soundfonts (font bundled theo deployment) — trước
+    # đây chỉ UPLOAD + SYSTEM → font bundled 404 → incognito (IndexedDB rỗng)
+    # không tải được font → instrument CÂM (browser thường dùng cache nên OK).
+    static_sf_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "static", "soundfonts")
+    for base_dir in [UPLOAD_SF_DIR, SYSTEM_SF_DIR, static_sf_dir]:
+        if not os.path.isdir(base_dir):
+            continue
+        # Prefer SF2: the client FluidSynth WASM cannot decode SF3 (Ogg Vorbis)
+        # samples, so any SF3 would play silence in the browser.
+        for fname in os.listdir(base_dir):
+            fbase, fext = os.path.splitext(fname)
+            if fext.lower() == ".sf2" and fbase.lower() == clean_id.lower():
+                full = os.path.join(base_dir, fname)
+                return FileResponse(full, media_type="application/octet-stream", filename="soundfont.sf2")
+        # Only an SF3 exists -> decompress it to a playable SF2 on demand (cached)
+        for fname in os.listdir(base_dir):
+            fbase, fext = os.path.splitext(fname)
+            if fext.lower() == ".sf3" and fbase.lower() == clean_id.lower():
+                full = os.path.join(base_dir, fname)
+                try:
+                    from app.core.soundfont_converter import SoundFontConverter
+                    sf2_path = os.path.join(UPLOAD_SF_DIR, clean_id + ".sf2")
+                    if os.path.exists(sf2_path) and os.path.getmtime(sf2_path) >= os.path.getmtime(full):
+                        return FileResponse(sf2_path, media_type="application/octet-stream", filename="soundfont.sf2")
+                    result = SoundFontConverter().sf3_to_sf2(full, sf2_path)
+                    if result != full and os.path.exists(result):
+                        return FileResponse(result, media_type="application/octet-stream", filename="soundfont.sf2")
+                except Exception as e:
+                    print(f"[soundfont-download] SF3->SF2 conversion failed for {full}: {e}")
+                return FileResponse(full, media_type="application/octet-stream", filename="soundfont.sf3")
+    raise HTTPException(status_code=404, detail="SoundFont asset not found")
+
+
 class RenderRequest(BaseModel):
     project_json: dict
     output_filename: Optional[str] = "render_output.wav"
@@ -106,8 +194,13 @@ async def render_project(
     req: RenderRequest,
     current_user: dict = Depends(get_current_user)
 ):
+    enforce_password_changed(current_user)
     engine = PythonRenderEngine()
-    output_path = os.path.join(settings.PROCESSED_DIR, req.output_filename or "render_output.wav")
+    # Prevent path traversal: strip any directory components and force .wav.
+    safe_name = os.path.basename((req.output_filename or "render_output.wav").replace("\\", "/"))
+    if not safe_name.lower().endswith(".wav"):
+        safe_name += ".wav"
+    output_path = os.path.join(settings.PROCESSED_DIR, safe_name)
     try:
         result_path = engine.render_project(req.project_json, output_path)
         return {"url": f"/static/audio/processed/{os.path.basename(result_path)}", "path": result_path}

app/api/v1/projects.py

@@ -2,9 +2,9 @@ import time
 import json
 import uuid
 import os
-from fastapi import APIRouter, HTTPException, Depends, Header
+from fastapi import APIRouter, HTTPException, Depends, Header, Query
 from pydantic import BaseModel
-from typing import Optional, Any, Dict
+from typing import Optional, Any, Dict, List
 from jsonschema import validate, ValidationError
 from app.models.user import get_db_connection
 from app.api.v1.auth import get_current_user, decode_token
@@ -18,6 +18,11 @@ def upgrade_project_json_if_needed(project_data: dict) -> dict:
         return project_data
     
     tracks = project_data.get("tracks", [])
+    # Legacy format stores item start times in SECONDS; convert using the real
+    # seconds-per-bar (old code hardcoded /4.0 which shifted every item's
+    # position for any tempo other than the one where 1 bar = 4s).
+    bpm_val = float(project_data.get("bpm", 120.0) or 120.0)
+    seconds_per_bar = (60.0 / bpm_val) * 4
     upgraded_tracks = []
     for t in tracks:
         track_id = str(t.get("id", ""))
@@ -33,11 +38,12 @@ def upgrade_project_json_if_needed(project_data: dict) -> dict:
                 "id": c.get("id"),
                 "name": c.get("name", "Audio Clip"),
                 "type": "AUDIO_ITEM",
-                "start_bar": c.get("startTime", 0.0) / 4.0,
-                "duration_bars": 4.0,
+                "start_bar": round(c.get("startTime", 0.0) / seconds_per_bar, 6),
+                "duration_bars": round((c.get("duration", 4.0) if c.get("duration") else 4.0) / seconds_per_bar, 6),
                 "clip_start_offset_bars": 0.0,
                 "source_data": {
                     "audio_file_url": f"/static/audio/uploads/{t.get('serverFileId')}" if t.get("serverFileId") else "",
+                    "server_file_id": t.get("serverFileId") or None,
                     "sample_rate": 44100,
                     "channels": 2,
                     "gain": 1.0
@@ -48,11 +54,11 @@ def upgrade_project_json_if_needed(project_data: dict) -> dict:
                 "id": m.get("id"),
                 "name": m.get("name", "MIDI Item"),
                 "type": "MIDI_ITEM",
-                "start_bar": m.get("startTime", 0.0) / 4.0,
-                "duration_bars": m.get("duration", 4.0),
+                "start_bar": round(m.get("startTime", 0.0) / seconds_per_bar, 6),
+                "duration_bars": round((m.get("duration", 4.0) or 4.0) / seconds_per_bar, 6),
                 "clip_start_offset_bars": 0.0,
                 "source_data": {
-                    "total_buffer_bars": m.get("duration", 8.0),
+                    "total_buffer_bars": round((m.get("duration", 8.0) or 8.0) / seconds_per_bar, 6),
                     "notes": m.get("notes", [])
                 }
             })
@@ -97,6 +103,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)
@@ -218,9 +234,11 @@ async def list_cloud_projects(current_user: dict = Depends(get_current_user)):
     conn = get_db_connection()
     cursor = conn.cursor()
     cursor.execute("""
-    SELECT id, name, size_bytes, updated_at FROM projects
-    WHERE user_id = ? AND is_temp = 0
-    ORDER BY updated_at DESC
+    SELECT p.id, p.name, p.size_bytes, p.updated_at,
+           (SELECT COUNT(*) FROM project_backups pb WHERE pb.project_id = p.id AND pb.user_id = p.user_id) as backup_count
+    FROM projects p
+    WHERE p.user_id = ? AND p.is_temp = 0
+    ORDER BY p.updated_at DESC
     """, (user_id,))
     rows = cursor.fetchall()
     conn.close()
@@ -230,7 +248,8 @@ async def list_cloud_projects(current_user: dict = Depends(get_current_user)):
             "id": r["id"],
             "name": r["name"],
             "size_mb": round(r["size_bytes"] / (1024 * 1024), 2),
-            "updated_at": r["updated_at"]
+            "updated_at": r["updated_at"],
+            "backup_count": r["backup_count"]
         } for r in rows
     ]
 
@@ -269,13 +288,30 @@ async def update_cloud_project(project_id: str, req: SaveProjectRequest, current
     conn = get_db_connection()
     cursor = conn.cursor()
     
-    cursor.execute("SELECT id FROM projects WHERE id = ? AND user_id = ? AND is_temp = 0", (project_id, user_id))
-    exists = cursor.fetchone()
-    if not exists:
+    cursor.execute("SELECT id, size_bytes FROM projects WHERE id = ? AND user_id = ? AND is_temp = 0", (project_id, user_id))
+    existing = cursor.fetchone()
+    if not existing:
         conn.close()
         raise HTTPException(status_code=404, detail="Không tìm thấy dự án để cập nhật")
-        
+    
     new_size_bytes = len(validated_data_json.encode("utf-8"))
+    
+    # Enforce storage quota (same rule as save_cloud_project — previously
+    # update bypassed the quota entirely).
+    cursor.execute("SELECT storage_limit_mb FROM user_quotas WHERE user_id = ?", (user_id,))
+    quota_row = cursor.fetchone()
+    storage_limit_mb = quota_row["storage_limit_mb"] if quota_row else 500
+    cursor.execute("SELECT SUM(size_bytes) as total_used FROM projects WHERE user_id = ? AND is_temp = 0", (user_id,))
+    used_row = cursor.fetchone()
+    used_bytes = (used_row["total_used"] if used_row and used_row["total_used"] else 0) - (existing["size_bytes"] or 0)
+    max_bytes = storage_limit_mb * 1024 * 1024
+    if used_bytes + new_size_bytes > max_bytes:
+        conn.close()
+        raise HTTPException(
+            status_code=400,
+            detail=f"Dung lượng dự án vượt quá hạn mức Quota ({storage_limit_mb}MB). Vui lòng dọn dẹp hoặc nâng cấp tài khoản."
+        )
+    
     now = time.time()
     
     cursor.execute("""
@@ -288,6 +324,115 @@ async def update_cloud_project(project_id: str, req: SaveProjectRequest, current
     conn.close()
     return {"success": True, "message": "Đã cập nhật dự án thành công"}
 
+class BackupConfigRequest(BaseModel):
+    max_count: int = 10
+
+@router.post("/cloud/{project_id}/backup")
+async def create_project_backup(project_id: str, current_user: dict = Depends(get_current_user)):
+    user_id = current_user["user_id"]
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    cursor.execute("SELECT name, data_json FROM projects WHERE id = ? AND user_id = ? AND is_temp = 0", (project_id, user_id))
+    row = cursor.fetchone()
+    if not row:
+        conn.close()
+        raise HTTPException(status_code=404, detail="Không tìm thấy dự án")
+    
+    backup_id = f"backup_{uuid.uuid4().hex[:12]}"
+    now = time.time()
+    size_bytes = len(row["data_json"].encode("utf-8"))
+    backup_name = f"[Backup] {row['name']} ({time.strftime('%Y-%m-%d %H:%M', time.localtime(now))})"
+    
+    cursor.execute("""
+    INSERT INTO project_backups (id, user_id, project_id, name, data_json, size_bytes, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    """, (backup_id, user_id, project_id, backup_name, row["data_json"], size_bytes, now))
+    
+    # Enforce retention limit: lấy max_count từ query param mặc định 10
+    cursor.execute("SELECT COUNT(*) as cnt FROM project_backups WHERE project_id = ? AND user_id = ?", (project_id, user_id))
+    count = cursor.fetchone()["cnt"]
+    max_backup = 10  # default
+    if count > max_backup:
+        excess = count - max_backup
+        cursor.execute("""
+        DELETE FROM project_backups WHERE id IN (
+            SELECT id FROM project_backups WHERE project_id = ? AND user_id = ?
+            ORDER BY created_at ASC LIMIT ?
+        )
+        """, (project_id, user_id, excess))
+    
+    conn.commit()
+    conn.close()
+    return {
+        "backup_id": backup_id,
+        "name": backup_name,
+        "created_at": now,
+        "max_backups": max_backup
+    }
+
+@router.get("/cloud/{project_id}/backups")
+async def list_project_backups(project_id: str, current_user: dict = Depends(get_current_user)):
+    user_id = current_user["user_id"]
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    cursor.execute("""
+    SELECT id, name, size_bytes, created_at FROM project_backups
+    WHERE project_id = ? AND user_id = ?
+    ORDER BY created_at DESC
+    """, (project_id, user_id))
+    rows = cursor.fetchall()
+    conn.close()
+    return [
+        {
+            "id": r["id"],
+            "name": r["name"],
+            "size_mb": round(r["size_bytes"] / (1024 * 1024), 2),
+            "created_at": r["created_at"]
+        } for r in rows
+    ]
+
+@router.delete("/cloud/backups/{backup_id}")
+async def delete_project_backup(backup_id: str, current_user: dict = Depends(get_current_user)):
+    user_id = current_user["user_id"]
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    cursor.execute("DELETE FROM project_backups WHERE id = ? AND user_id = ?", (backup_id, user_id))
+    conn.commit()
+    conn.close()
+    return {"success": True, "message": "Đã xóa bản backup"}
+
+class CleanupBackupsRequest(BaseModel):
+    keep: int = 10
+
+@router.post("/cloud/backups/cleanup")
+async def cleanup_all_backups(req: CleanupBackupsRequest, current_user: dict = Depends(get_current_user)):
+    user_id = current_user["user_id"]
+    keep = max(5, min(20, req.keep))
+    conn = get_db_connection()
+    cursor = conn.cursor()
+    
+    # Lấy tất cả project_id của user
+    cursor.execute("SELECT DISTINCT project_id FROM project_backups WHERE user_id = ?", (user_id,))
+    projects = cursor.fetchall()
+    total_deleted = 0
+    for p in projects:
+        pid = p["project_id"]
+        cursor.execute("SELECT COUNT(*) as cnt FROM project_backups WHERE project_id = ? AND user_id = ?", (pid, user_id))
+        cnt = cursor.fetchone()["cnt"]
+        if cnt > keep:
+            excess = cnt - keep
+            cursor.execute("""
+            DELETE FROM project_backups WHERE id IN (
+                SELECT id FROM project_backups WHERE project_id = ? AND user_id = ?
+                ORDER BY created_at ASC LIMIT ?
+            )
+            """, (pid, user_id, excess))
+            total_deleted += excess
+    
+    conn.commit()
+    conn.close()
+    return {"success": True, "deleted": total_deleted, "keep": keep}
+
 class RenderProjectRequest(BaseModel):
     sample_rate: Optional[int] = 44100
 

app/api/v1/user_config.py

@@ -96,7 +96,7 @@ async def get_user_ai_config(authorization: Optional[str] = Header(None)):
 async def save_user_ai_config(req: SaveAIConfigRequest, authorization: Optional[str] = Header(None)):
     uid = _get_user_id(authorization)
     configs = _load_ai_configs()
-    configs[uid] = [p.dict() for p in req.providers]
+    configs[uid] = [p.model_dump() for p in req.providers]
     _save_all(ai_configs=configs)
     return {
         "success": True,

app/core/auth.py

@@ -5,25 +5,69 @@ import time
 import base64
 import uuid
 import os
+import secrets
 from typing import Optional, Dict, Any
 from app.models.user import get_db_connection
 from app.config import settings
 
-SECRET_KEY = os.getenv("SECRET_KEY", "sonicforge_secret_key_super_secure_2026")
+COOKIE_NAME = "sf_token"
+X_AUTH_HEADER = "X-Auth-Token"
 
-def hash_password(password: str) -> str:
+def _load_or_create_secret_key() -> str:
+    """Persistent random SECRET_KEY.
+
+    Priority: env SECRET_KEY > {STORAGE_DIR}/.secret_key (auto-generated on
+    first run). Never falls back to a hardcoded value: a known secret lets
+    anyone forge admin tokens.
     """
-    Hash password using PBKDF2 HMAC SHA-256 with salt.
+    env_key = os.getenv("SECRET_KEY", "").strip()
+    if env_key:
+        return env_key
+    key_file = os.path.join(settings.STORAGE_DIR, ".secret_key")
+    try:
+        os.makedirs(settings.STORAGE_DIR, exist_ok=True)
+        if os.path.exists(key_file):
+            with open(key_file, "r") as f:
+                key = f.read().strip()
+            if len(key) >= 32:
+                return key
+        key = secrets.token_hex(32)
+        with open(key_file, "w") as f:
+            f.write(key)
+        return key
+    except Exception:
+        # Last resort: ephemeral random key (all tokens invalid on restart).
+        return secrets.token_hex(32)
+
+SECRET_KEY = _load_or_create_secret_key()
+
+def hash_password(password: str, salt: Optional[str] = None) -> str:
+    """
+    Hash password using PBKDF2 HMAC SHA-256 with a per-user random salt.
     Guarantees raw passwords are NEVER stored or exposed in plaintext.
+    Returns format: 'salt_hex:hashed_key_hex' (colon-delimited, stores both values).
+    If salt is provided, uses that salt (for verification).
+    If salt is None, generates a new 32-byte random salt.
     """
-    salt = b"sonicforge_crypto_salt_2026_secure_"
-    key = hashlib.pbkdf2_hmac('sha256', password.encode('utf-8'), salt, 100000)
-    return key.hex()
+    if salt is None:
+        salt = secrets.token_hex(32)
+    key = hashlib.pbkdf2_hmac('sha256', password.encode('utf-8'), salt.encode('utf-8'), 600000)
+    return f"{salt}:{key.hex()}"
 
-def verify_password(plain_password: str, hashed_password: str) -> bool:
-    """Verify plain password against PBKDF2 hashed password using constant-time comparison."""
-    computed_hash = hash_password(plain_password)
-    return hmac.compare_digest(computed_hash, hashed_password)
+def verify_password(plain_password: str, stored_value: str) -> bool:
+    """Verify plain password against stored 'salt:hash' using constant-time comparison.
+    Also supports legacy-format hash (hex only, without salt) for backward compatibility."""
+    if ':' in stored_value:
+        parts = stored_value.split(':', 1)
+        salt = parts[0]
+        expected_hash = parts[1]
+        computed = hash_password(plain_password, salt)
+        computed_hash = computed.split(':', 1)[1]
+        return hmac.compare_digest(computed_hash, expected_hash)
+    else:
+        expected_hash = stored_value
+        computed_hash = hashlib.pbkdf2_hmac('sha256', plain_password.encode('utf-8'), b"sonicforge_crypto_salt_2026_secure_", 600000).hex()
+        return hmac.compare_digest(computed_hash, expected_hash)
 
 def create_token(user_id: str, username: str, role: str, must_change_password: bool) -> str:
     payload = {
@@ -56,7 +100,7 @@ def decode_token(token: str) -> Optional[Dict[str, Any]]:
         return None
 
 def seed_admin():
-    """Seed default admin account on initial launch if not exists or update password hash if outdated."""
+    """Seed default admin account on initial launch only — never resets existing password."""
     conn = get_db_connection()
     cursor = conn.cursor()
     
@@ -64,9 +108,8 @@ def seed_admin():
     hashed_pwd = hash_password(default_pwd)
     now = time.time()
     
-    cursor.execute("SELECT id, hashed_password, must_change_password FROM users WHERE username = ?", ("admin",))
-    row = cursor.fetchone()
-    if not row:
+    cursor.execute("SELECT id FROM users WHERE username = ?", ("admin",))
+    if not cursor.fetchone():
         admin_id = str(uuid.uuid4())
         cursor.execute("""
         INSERT INTO users (id, username, email, hashed_password, role, must_change_password, created_at, is_active)
@@ -78,11 +121,6 @@ def seed_admin():
         VALUES (?, 10240, 64)
         """, (admin_id,))
         conn.commit()
-    else:
-        # Kiểm tra và sửa password admin mặc định nếu cần
-        if not verify_password(default_pwd, row["hashed_password"]):
-            cursor.execute("UPDATE users SET hashed_password = ?, must_change_password = 1 WHERE id = ?", (hashed_pwd, row["id"]))
-            conn.commit()
             
     conn.close()
 

app/core/render_engine.py

@@ -1,4 +1,4 @@
-import os
+import os, logging, math
 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
@@ -48,13 +87,33 @@ class PythonRenderEngine:
             return url_or_id
         return url_or_id
 
-    def render_session_container(self, session: dict, section_store: dict, bpm: float, time_sig_num: int, total_samples: int) -> np.ndarray:
+    def render_session_container(self, session: dict, section_store: dict, bpm: float, time_sig_num: int, total_samples: int, _cache: dict = None) -> np.ndarray:
         session_buffer = np.zeros((2, total_samples), dtype=np.float32)
 
-        for track in session.get("tracks", []):
+        # Solo semantics: when any track is soloed, only soloed tracks sound.
+        tracks = session.get("tracks", [])
+        solo_ids = {t.get("id") for t in tracks if t.get("solo")}
+
+        _channel_counter = 0
+
+        for track in tracks:
+            if solo_ids and track.get("id") not in solo_ids:
+                continue
             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)
@@ -70,8 +129,17 @@ class PythonRenderEngine:
                         try:
                             audio_data, sr = sf.read(resolved_path, dtype='float32')
                             if sr != self.sample_rate:
-                                # Resampling fallback if simple, otherwise skip
-                                pass
+                                # Proper resampling: previously a silent no-op that
+                                # played 48kHz audio at the wrong speed/pitch.
+                                from scipy.signal import resample_poly
+                                g = math.gcd(sr, self.sample_rate)
+                                audio_data = resample_poly(
+                                    audio_data,
+                                    up=self.sample_rate // g,
+                                    down=sr // g,
+                                    axis=-1,
+                                )
+                                sr = self.sample_rate
                             
                             # Handle channel mapping (Mono/Stereo)
                             if len(audio_data.shape) == 1:
@@ -95,7 +163,7 @@ class PythonRenderEngine:
                                 if actual_len > 0:
                                     track_buffer[:, start_sample:write_end] += sliced_audio[:, :actual_len]
                         except Exception as e:
-                            print(f"[RenderEngine] Error reading audio file {resolved_path}: {e}")
+                            logger.warning("[RenderEngine] Error reading audio file %s: %s", resolved_path, e)
 
                 elif item_type == "MIDI_ITEM":
                     source_data = item.get("source_data", {})
@@ -120,15 +188,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 +236,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'
                                     )
@@ -188,21 +299,27 @@ class PythonRenderEngine:
                             actual_len = min(synth_buffer.shape[1], total_samples)
                             track_buffer[:, :actual_len] += synth_buffer[:, :actual_len]
                         except Exception as e:
-                            print(f"[RenderEngine] Error rendering MIDI: {e}")
+                            logger.warning("[RenderEngine] Error rendering MIDI: %s", e)
 
                 elif item_type == "SECTION_ITEM":
                     source_data = item.get("source_data", {})
                     sec_id = source_data.get("referenced_section_id", "")
                     if sec_id and sec_id in section_store:
-                        # Render nested section recursively
-                        sec_container = section_store[sec_id]
-                        sec_buffer = self.render_session_container(
-                            session=sec_container,
-                            section_store=section_store,
-                            bpm=bpm,
-                            time_sig_num=time_sig_num,
-                            total_samples=total_samples
-                        )
+                        # Render nested section recursively, cached per section id
+                        # so repeated section instances don't re-render every time.
+                        cache = _cache if _cache is not None else {}
+                        if sec_id in cache:
+                            sec_buffer = cache[sec_id]
+                        else:
+                            sec_buffer = self.render_session_container(
+                                session=section_store[sec_id],
+                                section_store=section_store,
+                                bpm=bpm,
+                                time_sig_num=time_sig_num,
+                                total_samples=total_samples,
+                                _cache=cache,
+                            )
+                            cache[sec_id] = sec_buffer
                         
                         # Apply non-destructive crop/slicing on section buffer
                         if offset_sample < total_samples:
@@ -231,7 +348,7 @@ class PythonRenderEngine:
                         board = Pedalboard([Chorus(rate_hz=1.5, depth=0.25)])
                         track_buffer = board(track_buffer, sample_rate=self.sample_rate)
                     except Exception as e:
-                        print(f"[RenderEngine] Pedalboard Chorus failed: {e}")
+                        logger.warning("[RenderEngine] Pedalboard Chorus failed: %s", e)
                 else:
                     # Fallback chorus using simple LFO delay modulation in scipy/numpy
                     try:
@@ -245,14 +362,14 @@ class PythonRenderEngine:
                             wet[ch, :] = track_buffer[ch, indices]
                         track_buffer = dry + wet * 0.5
                     except Exception as e:
-                        print(f"[RenderEngine] Fallback Chorus failed: {e}")
+                        logger.warning("[RenderEngine] Fallback Chorus failed: %s", e)
             elif fx_type == "reverb":
                 if HAS_PEDALBOARD:
                     try:
                         board = Pedalboard([Reverb(room_size=0.5, wet_level=0.4, dry_level=0.6)])
                         track_buffer = board(track_buffer, sample_rate=self.sample_rate)
                     except Exception as e:
-                        print(f"[RenderEngine] Pedalboard Reverb failed: {e}")
+                        logger.warning("[RenderEngine] Pedalboard Reverb failed: %s", e)
                 else:
                     # Fallback reverb using exponentially decaying noise room impulse response
                     try:
@@ -272,7 +389,7 @@ class PythonRenderEngine:
                             wet[ch, :] = conv
                         track_buffer = dry + wet * 0.4
                     except Exception as e:
-                        print(f"[RenderEngine] Fallback Reverb failed: {e}")
+                        logger.warning("[RenderEngine] Fallback Reverb failed: %s", e)
 
             # Process track volume
             if HAS_PEDALBOARD:
@@ -314,7 +431,8 @@ class PythonRenderEngine:
             section_store=section_store,
             bpm=bpm,
             time_sig_num=time_sig_num,
-            total_samples=total_samples
+            total_samples=total_samples,
+            _cache={},
         )
 
         # Normalization to prevent clipping

app/core/soundfont_converter.py

@@ -0,0 +1,551 @@
+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 _encode_sample_ogg(self, pcm: bytes, rate: int, tmp_dir: str) -> bytes:
+        """Encode a single mono 16-bit PCM slice to an Ogg Vorbis stream."""
+        tmp_wav = os.path.join(tmp_dir, "sample_tmp.wav")
+        tmp_ogg = os.path.join(tmp_dir, "sample_tmp.ogg")
+        try:
+            with open(tmp_wav, "wb") as fw:
+                with wave.open(fw, "wb") as w:
+                    w.setnchannels(1)
+                    w.setsampwidth(2)
+                    w.setframerate(rate)
+                    w.writeframes(pcm)
+            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:
+                return fo.read()
+        except Exception as e:
+            logger.error(f"Sample OGG encode failed: {e}")
+            return b""
+        finally:
+            for p in [tmp_wav, tmp_ogg]:
+                try:
+                    if os.path.exists(p):
+                        os.remove(p)
+                except Exception:
+                    pass
+
+    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 (PCM sample data) 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
+
+        # Locate shdr (sample headers) inside the pdta LIST
+        pdta = _find_list_of_type(data, b"pdta", 12)
+        if not pdta:
+            logger.warning("No pdta LIST found")
+            return False
+        _, _, pdta_size, pdta_data_off = pdta
+        shdr = _find_chunk_in_list(data, b"shdr", pdta_data_off, pdta_size - 4)
+        if not shdr:
+            logger.warning("No shdr chunk found")
+            return False
+        _, _, shdr_size, shdr_data_off = shdr
+        if shdr_size <= 0 or shdr_size % 46 != 0:
+            logger.warning(f"Invalid shdr size {shdr_size}")
+            return False
+        n_samples = shdr_size // 46
+
+        # Locate ifil (version) inside the INFO LIST
+        ifil_abs = None
+        info = _find_list_of_type(data, b"INFO", 12)
+        if info:
+            _, _, info_size, info_data_off = info
+            ifil = _find_chunk_in_list(data, b"ifil", info_data_off, info_size - 4)
+            if ifil:
+                ifil_abs = ifil[3]
+
+        import tempfile
+        tmp_dir = tempfile.mkdtemp(prefix="sf3conv_")
+        ogg_parts = []
+        new_shdr = bytearray()
+        byte_offset = 0
+        ogg_bytes = 0
+        try:
+            for i in range(n_samples):
+                base = shdr_data_off + i * 46
+                # shdr layout: name[20] | start(u32) end(u32) loopstart(u32) loopend(u32) samplerate(i32) ...
+                start, end, startloop, endloop, rate = struct.unpack("<IIIIi", data[base + 20:base + 40])
+                sampletype = struct.unpack("<H", data[base + 44:base + 46])[0]
+                ogg_stream = b""
+                if end >= start and start * 2 < len(sample_data):
+                    pcm = sample_data[start * 2:(end + 1) * 2]
+                    if len(pcm) >= 4:
+                        safe_rate = rate if 1000 < rate < 192000 else 44100
+                        ogg_stream = self._encode_sample_ogg(pcm, safe_rate, tmp_dir)
+                # SF3: start/end are byte offsets into the concatenated OGG stream.
+                # FluidSynth treats shdr `end` as EXCLUSIVE (reads [start..end-1]),
+                # so end = start + ogg length.
+                new_start = byte_offset
+                new_end = byte_offset + len(ogg_stream)
+                # OGG loop pointers are relative to the individual decompressed sample
+                new_sloop = (startloop - start) if (startloop > start and startloop <= end) else 0
+                new_eloop = (endloop - start) if (endloop > start and endloop <= end) else 0
+                # Mark the sample as Ogg Vorbis compressed (FLUID_SAMPLETYPE_OGG_VORBIS = 0x20)
+                new_stype = sampletype | 0x20
+                new_shdr += data[base:base + 20]                       # sample name
+                new_shdr += struct.pack("<IIIIi", new_start, new_end, new_sloop, new_eloop, rate)
+                new_shdr += data[base + 40:base + 44]                  # originalpitch, correction, samplelink
+                new_shdr += struct.pack("<H", new_stype)
+                ogg_parts.append(ogg_stream)
+                ogg_bytes += len(ogg_stream)
+                byte_offset = new_start + len(ogg_stream)
+                if len(ogg_stream) % 2 == 1:
+                    ogg_parts.append(b"\x00")
+                    byte_offset += 1
+
+            if not ogg_parts:
+                logger.warning("No samples to encode")
+                return False
+
+            ogg_padded = b"".join(ogg_parts)
+            if len(ogg_padded) % 2 == 1:
+                ogg_padded += b"\x00"
+            new_smpl_size = len(ogg_padded)
+            old_padded = smpl_old_size + (1 if smpl_old_size % 2 == 1 else 0)
+            delta = len(ogg_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 (excl. id)
+            out.extend(b"smpl")                        # chunk id (required for valid SF3)
+            out.extend(struct.pack("<I", new_smpl_size))  # new smpl size
+            out.extend(ogg_padded)                     # concatenated per-sample OGG streams
+            rest_off = smpl_head_off + 8 + old_padded
+            rest = bytearray(data[rest_off:])
+            # Patch the shdr sample headers inside the pdta copy
+            shdr_in_rest = shdr_data_off - rest_off
+            if shdr_in_rest < 0 or shdr_in_rest + shdr_size > len(rest):
+                logger.warning("shdr not found after smpl chunk")
+                return False
+            rest[shdr_in_rest:shdr_in_rest + shdr_size] = new_shdr
+            out.extend(rest)
+
+            data_out = bytes(out)
+
+            # SF3 requires version 3.0 so FluidSynth treats it as an SF3 file
+            if ifil_abs is not None and ifil_abs + 4 <= len(data_out):
+                data_out = data_out[:ifil_abs] + struct.pack("<HH", 3, 0) + data_out[ifil_abs + 4:]
+
+            # 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
+            new_total = len(data_out) - 8
+            data_out = _update_size(data_out, 4, new_total)
+
+            with open(sf3_path, "wb") as fout:
+                fout.write(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
+
+            logger.info(f"Converted {n_samples} samples -> {ogg_bytes} bytes OGG ({100 * (1 - ogg_bytes / max(len(sample_data), 1)):.0f}% smaller)")
+            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:
+            try:
+                import shutil
+                shutil.rmtree(tmp_dir, ignore_errors=True)
+            except Exception:
+                pass
+
+    @staticmethod
+    def _sf3_plays_audio(path: str) -> bool:
+        """Verify a SoundFont actually loads and renders audible audio (guards
+        against shipping malformed SF3 files that silently play nothing).
+
+        Uses the low-level CFFI binding (new_fluid_synth / write_float) — the
+        high-level Synth() class does not exist in this binding, so it is never
+        used here.
+        """
+        if not os.path.exists(path):
+            return False
+        try:
+            import fluidsynth as _fs
+            import numpy as np
+            _settings = _fs.new_fluid_settings()
+            _fl = _fs.new_fluid_synth(_settings)
+            try:
+                h = _fs.fluid_synth_sfload(_fl, path.encode("utf-8"), 1)
+                if h < 0:
+                    return False
+                _fs.fluid_synth_program_select(_fl, 0, h, 0, 0)
+                _fs.fluid_synth_noteon(_fl, 0, 60, 100)
+                frames = 8820  # 0.2s
+                buf = np.zeros(frames * 2, dtype=np.float32)
+                _fs.fluid_synth_write_float(
+                    _fl, frames, buf.ctypes.data, 0, 1,
+                    buf.ctypes.data + frames * 4, 0, 1
+                )
+                _fs.fluid_synth_noteoff(_fl, 0, 60)
+                rms = float(np.sqrt(np.mean(buf ** 2)))
+                return rms > 1e-4
+            finally:
+                try:
+                    _fs.delete_fluid_synth(_fl)
+                except Exception:
+                    pass
+        except Exception:
+            return False
+
+    @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"
+
+        # Reuse a working SF3 if it is newer than the SF2 AND actually plays
+        # audio. Malformed SF3s (e.g. produced by an older converter) are
+        # re-converted automatically instead of being shipped silently broken.
+        if os.path.exists(sf3_path) and os.path.getmtime(sf3_path) >= os.path.getmtime(sf2_path):
+            if self._sf3_plays_audio(sf3_path):
+                logger.info(f"SF3 already up-to-date: {sf3_path}")
+                return sf3_path
+            logger.warning(f"Existing SF3 does not play audio, re-converting: {sf3_path}")
+            try:
+                os.remove(sf3_path)
+            except Exception:
+                pass
+
+        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):
+                    if self._sf3_plays_audio(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
+                    # Conversion produced a broken file — never ship it
+                    logger.warning(f"Converted SF3 failed audio verification, removing: {sf3_path}")
+                    try:
+                        os.remove(sf3_path)
+                    except Exception:
+                        pass
+                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 sf3_to_sf2(self, sf3_path: str, sf2_path: str = None) -> str:
+        """Convert an SF3 (Ogg Vorbis samples) soundfont into a playable SF2.
+
+        The client FluidSynth WASM cannot decode Ogg Vorbis/SF3 samples, so any
+        SF3 soundfont (converted or uploaded) plays silence. Decompressing to
+        SF2 makes every instrument audible again.
+        """
+        if not os.path.exists(sf3_path):
+            raise FileNotFoundError(f"Source SF3 file not found: {sf3_path}")
+
+        try:
+            with open(sf3_path, "rb") as f:
+                data = f.read()
+        except Exception as e:
+            raise IOError(f"Cannot read {sf3_path}: {e}")
+
+        if len(data) < 12 or data[:4] != b"RIFF" or data[8:12] != b"sfbk":
+            raise ValueError(f"Not a valid SoundFont file: {sf3_path}")
+
+        smpl = _find_chunk(data, b"smpl")
+        if not smpl:
+            raise ValueError("No smpl chunk found")
+        smpl_head_off, _, smpl_old_size, smpl_data_off = smpl
+        sample_data = data[smpl_data_off:smpl_data_off + smpl_old_size]
+
+        pdta = _find_list_of_type(data, b"pdta", 12)
+        if not pdta:
+            raise ValueError("No pdta LIST found")
+        _, _, pdta_size, pdta_data_off = pdta
+        shdr = _find_chunk_in_list(data, b"shdr", pdta_data_off, pdta_size - 4)
+        if not shdr:
+            raise ValueError("No shdr chunk found")
+        _, _, shdr_size, shdr_data_off = shdr
+        if shdr_size <= 0 or shdr_size % 46 != 0:
+            raise ValueError(f"Invalid shdr size {shdr_size}")
+        n_samples = shdr_size // 46
+
+        ifil_abs = None
+        info = _find_list_of_type(data, b"INFO", 12)
+        if info:
+            _, _, info_size, info_data_off = info
+            ifil = _find_chunk_in_list(data, b"ifil", info_data_off, info_size - 4)
+            if ifil:
+                ifil_abs = ifil[3]
+
+        import tempfile
+        tmp_dir = tempfile.mkdtemp(prefix="sf2conv_")
+        pcm_parts = []
+        new_shdr = bytearray()
+        frame_offset = 0
+        total_pcm_bytes = 0
+        try:
+            for i in range(n_samples):
+                base = shdr_data_off + i * 46
+                name = data[base:base + 20]
+                start, end, loopstart, loopend, rate = struct.unpack("<IIIIi", data[base + 20:base + 40])
+                sampletype = struct.unpack("<H", data[base + 44:base + 46])[0]
+                frames = 0
+                pcm = b""
+                if end > start and start < len(sample_data):
+                    # FluidSynth reads the OGG region as [start..end-1]
+                    ogg = sample_data[start:min(end, len(sample_data))]
+                    if len(ogg) >= 4 and ogg[:4] == b"OggS":
+                        pcm = self._decode_sample_ogg(ogg, tmp_dir)
+                        frames = len(pcm) // 2
+                new_start = frame_offset
+                new_end = frame_offset + frames
+                # SF3 loop points are relative to the decompressed sample; SF2 needs absolute
+                new_loopstart = loopstart + new_start if (loopstart or loopend) else 0
+                new_loopend = loopend + new_start if (loopstart or loopend) else 0
+                # Clear the Ogg Vorbis flag; keep mono/left/right/linked flags
+                new_stype = sampletype & ~0x20
+                new_shdr += name
+                new_shdr += struct.pack("<IIIIi", new_start, new_end, new_loopstart, new_loopend, rate)
+                new_shdr += data[base + 40:base + 44]
+                new_shdr += struct.pack("<H", new_stype)
+                pcm_parts.append(pcm)
+                frame_offset += frames
+                if frames:
+                    total_pcm_bytes += frames * 2
+
+            if total_pcm_bytes == 0:
+                logger.warning("SF3 contained no decodable samples")
+                return sf3_path
+
+            new_smpl_size = total_pcm_bytes
+            if new_smpl_size % 2 == 1:
+                new_smpl_size += 1
+            old_padded = smpl_old_size + (1 if smpl_old_size % 2 == 1 else 0)
+            delta = new_smpl_size - old_padded
+
+            out = bytearray()
+            out.extend(data[:smpl_head_off])
+            out.extend(b"smpl")
+            out.extend(struct.pack("<I", new_smpl_size))
+            for part in pcm_parts:
+                out.extend(part)
+            if total_pcm_bytes % 2 == 1:
+                out.extend(b"\x00")
+            rest_off = smpl_head_off + 8 + old_padded
+            rest = bytearray(data[rest_off:])
+            shdr_in_rest = shdr_data_off - rest_off
+            if shdr_in_rest < 0 or shdr_in_rest + shdr_size > len(rest):
+                logger.warning("shdr not found after smpl chunk")
+                return sf3_path
+            rest[shdr_in_rest:shdr_in_rest + shdr_size] = new_shdr
+            out.extend(rest)
+
+            data_out = bytes(out)
+
+            # Back to SF2 version 2.01
+            if ifil_abs is not None and ifil_abs + 4 <= len(data_out):
+                data_out = data_out[:ifil_abs] + struct.pack("<HH", 2, 1) + data_out[ifil_abs + 4:]
+
+            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)
+
+            data_out = _update_size(data_out, 4, len(data_out) - 8)
+
+            sf2_path = sf2_path or (os.path.splitext(sf3_path)[0] + ".sf2")
+            with open(sf2_path, "wb") as fout:
+                fout.write(data_out)
+            logger.info(f"Converted SF3 -> SF2: {sf2_path} ({os.path.getsize(sf2_path) / 1048576:.1f} MB)")
+            return sf2_path
+        finally:
+            try:
+                import shutil
+                shutil.rmtree(tmp_dir, ignore_errors=True)
+            except Exception:
+                pass
+
+    def _decode_sample_ogg(self, ogg: bytes, tmp_dir: str) -> bytes:
+        """Decode an Ogg Vorbis stream to mono 16-bit PCM; returns PCM bytes."""
+        tmp_ogg = os.path.join(tmp_dir, "sample.ogg")
+        tmp_pcm = os.path.join(tmp_dir, "sample.pcm")
+        try:
+            with open(tmp_ogg, "wb") as fo:
+                fo.write(ogg)
+            r = subprocess.run(
+                ["ffmpeg", "-y", "-v", "error", "-i", tmp_ogg, "-f", "s16le", "-ac", "1", tmp_pcm],
+                capture_output=True, timeout=600)
+            if r.returncode != 0:
+                logger.warning(f"OGG decode failed: {r.stderr.decode(errors='replace')[:120]}")
+                return b""
+            with open(tmp_pcm, "rb") as fp:
+                return fp.read()
+        except Exception as e:
+            logger.warning(f"OGG decode error: {e}")
+            return b""
+        finally:
+            for p in [tmp_ogg, tmp_pcm]:
+                try:
+                    if os.path.exists(p):
+                        os.remove(p)
+                except Exception:
+                    pass
+
+    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, catalog: dict = None) -> dict:
+        catalog = catalog if catalog is not None else 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/soundfont_scanner.py

@@ -0,0 +1,129 @@
+import os
+import json
+import time
+import logging
+import threading
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+TRACK_FILE = os.path.join(settings.STORAGE_DIR, "sf_scan_state.json")
+SYSTEM_SF_DIR = "/opt/daw_engine/soundfonts"
+UPLOAD_SF_DIR = os.path.join(settings.STORAGE_DIR, "soundfonts")
+
+
+def _file_sig(path: str) -> tuple:
+    s = os.path.getsize(path)
+    m = os.path.getmtime(path)
+    return (s, m)
+
+
+class SoundFontAutoScanner:
+    def __init__(self, system_sf_dir=SYSTEM_SF_DIR, upload_sf_dir=UPLOAD_SF_DIR):
+        self.system_sf_dir = system_sf_dir
+        self.upload_sf_dir = upload_sf_dir
+        self._catalog = {}
+        self._lock = threading.Lock()
+        self._state = self._load_state()
+
+    def _load_state(self) -> dict:
+        if not os.path.exists(TRACK_FILE):
+            return {}
+        try:
+            with open(TRACK_FILE) as f:
+                return json.load(f)
+        except Exception as e:
+            logger.warning("scan_state load failed: %s", e)
+            return {}
+
+    def _save_state(self):
+        os.makedirs(os.path.dirname(TRACK_FILE), exist_ok=True)
+        with open(TRACK_FILE, "w") as f:
+            json.dump(self._state, f, indent=2)
+
+    def _sf_files(self, directory: str) -> list:
+        if not os.path.isdir(directory):
+            return []
+        out = []
+        for fname in os.listdir(directory):
+            if fname.lower().endswith((".sf2", ".sf3")):
+                out.append((fname, os.path.join(directory, fname)))
+        return out
+
+    def _inspect_single(self, fname: str, full: str, inspector) -> dict:
+        if fname.lower().endswith(".sf2"):
+            sf_info = inspector.inspect_sf2_file(full) or {}
+        else:
+            sf_info = {}
+        if not sf_info.get("soundfont_id"):
+            sf_id = os.path.splitext(fname)[0].lower()
+            sf_info = {
+                "soundfont_id": sf_id,
+                "filename": fname,
+                "total_instruments": 0,
+                "instruments": [],
+                "_sf3": True
+            }
+        return sf_info
+
+    def scan_once(self) -> bool:
+        from app.core.soundfont_inspector import SoundFontInspector
+        inspector = SoundFontInspector(self.system_sf_dir, self.upload_sf_dir)
+        found_new = False
+        dirs = [(self.system_sf_dir, "system")]
+        if self.upload_sf_dir and os.path.isdir(self.upload_sf_dir):
+            dirs.append((self.upload_sf_dir, "upload"))
+
+        for directory, source in dirs:
+            for fname, full in self._sf_files(directory):
+                sf_id = os.path.splitext(fname)[0].lower()
+                key = f"{source}:{sf_id}"
+                sig = _file_sig(full)
+                prev = self._state.get(key)
+                unchanged = prev and prev["size"] == sig[0] and prev["mtime"] == sig[1]
+                if unchanged and sf_id in self._catalog:
+                    continue
+                if unchanged:
+                    with self._lock:
+                        if sf_id in self._catalog:
+                            continue
+                        sf_info = self._inspect_single(fname, full, inspector)
+                        self._catalog[sf_id] = sf_info
+                    continue
+                found_new = True
+                logger.info("New/changed SF detected: %s", fname)
+                sf_info = self._inspect_single(fname, full, inspector)
+                with self._lock:
+                    self._catalog[sf_id] = sf_info
+                    self._state[key] = {"size": sig[0], "mtime": sig[1], "file": fname}
+
+        if found_new:
+            self._save_state()
+            inspector.invalidate_catalog_cache()
+        return found_new
+
+    def scan_loop(self, interval: int = 30, stop_event: threading.Event = None):
+        logger.info("SF auto-scanner started (interval=%ds)", interval)
+        self.scan_once()
+        while not (stop_event and stop_event.is_set()):
+            time.sleep(interval)
+            try:
+                self.scan_once()
+            except Exception as e:
+                logger.error("scan cycle error: %s", e)
+
+    def start_background(self, interval: int = 30) -> threading.Event:
+        ev = threading.Event()
+        t = threading.Thread(target=self.scan_loop, args=(interval, ev), daemon=True)
+        t.start()
+        return ev
+
+    def get_catalog(self) -> dict:
+        with self._lock:
+            return dict(self._catalog)
+
+    def get_instruments(self, sf_id: str) -> list:
+        entry = self._catalog.get(sf_id)
+        if entry:
+            return entry.get("instruments", [])
+        return []

app/core/vst_engine.py

@@ -2,7 +2,7 @@
 import os
 import numpy as np
 import functools
-from ctypes import c_int, c_char_p, c_void_p
+from ctypes import c_char_p
 
 def midi_note_to_freq(note_number: int) -> float:
     return 440.0 * (2.0 ** ((note_number - 69) / 12.0))
@@ -110,7 +110,12 @@ def get_plugin_manager(vst_dir="/opt/daw_engine/vst3", sf_dir="/opt/daw_engine/s
     return _PLUGIN_MANAGER_INSTANCE
 
 def load_soundfont_cached(path: str):
-    """Return a cached FluidSynth instance for path, incrementing refcount."""
+    """Return a cached low-level FluidSynth instance for path, incrementing refcount.
+
+    Uses the CFFI binding API (new_fluid_synth / fluid_synth_sfload) — the same
+    API render_engine relies on. The high-level `FluidSynth()`/`Synth()` classes
+    do not exist in this binding, so they are never used here.
+    """
     global _FLUID_CACHE
     if not HAS_PYFLUIDSYNTH:
         return None
@@ -119,10 +124,15 @@ def load_soundfont_cached(path: str):
         _FLUID_CACHE[path] = (fl, ref + 1)
         return fl
     try:
-        import fluidsynth
-        fl = fluidsynth.FluidSynth(sample_rate=44100, gain=0.5)
-        font_id = fl.sfload(path)
-        fl.program_select(0, font_id, 0, 0)
+        import fluidsynth as _fs
+        _settings = _fs.new_fluid_settings()
+        _fs.fluid_settings_setnum(_settings, b'synth.sample-rate', 44100.0)
+        fl = _fs.new_fluid_synth(_settings)
+        font_id = _fs.fluid_synth_sfload(fl, path.encode("utf-8"), 1)
+        if font_id < 0:
+            _fs.delete_fluid_synth(fl)
+            return None
+        _fs.fluid_synth_program_select(fl, 0, font_id, 0, 0)
         _FLUID_CACHE[path] = (fl, 1)
         return fl
     except Exception:
@@ -136,7 +146,8 @@ def release_soundfont(path: str):
     fl, ref = _FLUID_CACHE[path]
     if ref <= 1:
         try:
-            fl.delete()
+            import fluidsynth as _fs
+            _fs.delete_fluid_synth(fl)
         except Exception:
             pass
         del _FLUID_CACHE[path]
@@ -163,12 +174,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 +190,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:
@@ -239,38 +256,47 @@ class PluginManager:
                 if base == sf_id or base == sf_id.replace("sf_", ""):
                     path = os.path.join(d, f)
                     try:
-                        import fluidsynth
-                        fl = fluidsynth.Synth()
-                        fid = fl.sfload(path)
-                        if fid < 0:
-                            fl.delete()
-                            continue
-                        presets = []
-                        _fl = fluidsynth._fl
-                        _fl.fluid_synth_get_sfont_by_id.restype = c_void_p
-                        _fl.fluid_preset_get_name.restype = c_char_p
-                        _fl.fluid_sfont_get_preset.restype = c_void_p
-                        sfont_ptr = _fl.fluid_synth_get_sfont_by_id(c_void_p(fl.synth), c_int(fid))
-                        if sfont_ptr:
-                            for bank in range(0, 2):
-                                for prog_num in range(0, 128):
-                                    try:
-                                        preset = fluidsynth.fluid_sfont_get_preset(sfont_ptr, c_int(bank), c_int(prog_num))
-                                    except Exception:
-                                        break
-                                    if preset:
-                                        name_ptr = fluidsynth.fluid_preset_get_name(preset)
-                                        if name_ptr:
-                                            name_val = c_char_p(name_ptr).value
-                                            if name_val:
-                                                presets.append({
-                                                    "bank": bank,
-                                                    "program": prog_num,
-                                                    "name": name_val.decode("utf-8", errors="replace")
-                                                })
-                        fl.delete()
-                        _SF_INSTRUMENTS_CACHE[sf_id] = presets[:256]
-                        return presets[:256]
+                        import fluidsynth as _fs
+                        # Low-level CFFI API (same as render_engine); never use
+                        # the high-level Synth() class that this binding lacks.
+                        _settings = _fs.new_fluid_settings()
+                        _synth = _fs.new_fluid_synth(_settings)
+                        try:
+                            fid = _fs.fluid_synth_sfload(_synth, path.encode("utf-8"), 1)
+                            if fid < 0:
+                                continue
+                            sfont = _fs.fluid_synth_get_sfont_by_id(_synth, fid)
+                            presets = []
+                            if sfont:
+                                for bank in range(0, 2):
+                                    for prog_num in range(0, 128):
+                                        try:
+                                            preset = _fs.fluid_sfont_get_preset(sfont, bank, prog_num)
+                                        except Exception:
+                                            break
+                                        if preset:
+                                            try:
+                                                name_ptr = _fs.fluid_preset_get_name(preset)
+                                                if name_ptr:
+                                                    if hasattr(_fs, "ffi"):
+                                                        raw = _fs.ffi.string(name_ptr)
+                                                    else:
+                                                        raw = c_char_p(name_ptr).value
+                                                    if raw:
+                                                        presets.append({
+                                                            "bank": bank,
+                                                            "program": prog_num,
+                                                            "name": raw.decode("utf-8", errors="replace")
+                                                        })
+                                            except Exception:
+                                                continue
+                            _SF_INSTRUMENTS_CACHE[sf_id] = presets[:256]
+                            return presets[:256]
+                        finally:
+                            try:
+                                _fs.delete_fluid_synth(_synth)
+                            except Exception:
+                                pass
                     except Exception:
                         import traceback; traceback.print_exc()
         _SF_INSTRUMENTS_CACHE[sf_id] = []
@@ -286,11 +312,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 +343,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,8 +1,11 @@
 import os
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
-from fastapi.responses import HTMLResponse
+from fastapi.responses import HTMLResponse, FileResponse
 from fastapi.staticfiles import StaticFiles
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.gzip import GZipMiddleware
 from app.config import settings
 from app.api.v1.audio import router as audio_router
 from app.api.v1.tasks import router as tasks_router
@@ -12,23 +15,42 @@ from app.api.v1.admin import router as admin_router
 from app.api.v1.projects import router as projects_router
 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.ai_presets import router as ai_presets_router
 from app.api.v1.plugins import router as plugins_router
+from app.api.v1.media import router as media_router
 from app.core.auth import seed_admin
+from app.core.soundfont_scanner import SoundFontAutoScanner
 
 # Ensure storage directories exist
 os.makedirs(settings.UPLOADS_DIR, exist_ok=True)
 os.makedirs(settings.PROCESSED_DIR, exist_ok=True)
 
-app = FastAPI(title="SonicForge API Engine")
+_SF_SCANNER_STOP = None
 
-from fastapi.middleware.gzip import GZipMiddleware
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    seed_admin()
+    scanner = SoundFontAutoScanner()
+    global _SF_SCANNER_STOP
+    _SF_SCANNER_STOP = scanner.start_background(interval=30)
+    yield
+    # Shutdown
+    if _SF_SCANNER_STOP is not None:
+        _SF_SCANNER_STOP.set()
+
+
+app = FastAPI(title="SonicForge API Engine", lifespan=lifespan)
 
 app.add_middleware(GZipMiddleware, minimum_size=500)
 
+# Auth is token/cookie based (no cookies required for CORS), so credentials are
+# disabled — "*" + allow_credentials=True is rejected by browsers anyway.
 app.add_middleware(
     CORSMiddleware,
     allow_origins=["*"],
-    allow_credentials=True,
+    allow_credentials=False,
     allow_methods=["*"],
     allow_headers=["*"],
 )
@@ -48,12 +70,10 @@ app.include_router(admin_router, prefix="/api/v1/admin", tags=["admin"])
 app.include_router(projects_router, prefix="/api/v1/projects", tags=["projects"])
 app.include_router(user_config_router, prefix="/api/v1/user", tags=["user_config"])
 app.include_router(ai_proxy_router, prefix="/api/v1/ai", tags=["ai"])
+app.include_router(ai_presets_router, prefix="/api/v1/ai", tags=["ai"])
 app.include_router(plugins_router, prefix="/api/v1/plugins", tags=["plugins"])
+app.include_router(media_router, prefix="/api/v1/media", tags=["media"])
 
-# Seed admin user on startup
-@app.on_event("startup")
-async def startup_seed_admin():
-    seed_admin()
 
 @app.get("/", response_class=HTMLResponse)
 async def get_index():
@@ -61,13 +81,26 @@ async def get_index():
     if not os.path.exists(index_path):
         return HTMLResponse(content=f"<h1>SonicForge Studio: index.html not found at {index_path}</h1>", status_code=404)
     with open(index_path, "r", encoding="utf-8") as file:
-        return HTMLResponse(content=file.read(), status_code=200)
+        resp = HTMLResponse(content=file.read(), status_code=200)
+        # no-cache: index.html PHẢI luôn mới (các bundle JS dùng ?v= để bust) —
+        # nếu browser cache HTML cũ → stamp cũ → tải bundle cũ (bug "không load
+        # được bundle mới" ở incognito — cache heuristic không có Cache-Control).
+        resp.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
+        return resp
+
 
 @app.get("/favicon.svg")
 async def get_favicon():
-    import os
     favicon_path = os.path.join(settings.TEMPLATES_DIR, "favicon.svg")
     if os.path.exists(favicon_path):
-        from fastapi.responses import FileResponse
         return FileResponse(favicon_path, media_type="image/svg+xml")
     return HTMLResponse(content="", status_code=404)
+
+
+@app.get("/ai-prompt-generator", response_class=HTMLResponse)
+async def get_ai_prompt_generator():
+    md_path = os.path.join(settings.BASE_DIR, "md", "49_AI_PROMPT_GENERATOR.md")
+    if not os.path.exists(md_path):
+        return HTMLResponse(content="<h1>File not found</h1>", status_code=404)
+    with open(md_path, "r", encoding="utf-8") as file:
+        return HTMLResponse(content=file.read(), status_code=200)

app/models/project_schema.json

@@ -45,6 +45,7 @@
         "id": { "type": "string" },
         "name": { "type": "string" },
         "type": { "type": "string", "enum": ["AUDIO", "MIDI", "SECTION"] },
+        "color": { "type": ["string", "null"], "default": null },
         "volume_db": { "type": "number", "default": 0.0 },
         "pan": { "type": "number", "minimum": -1.0, "maximum": 1.0, "default": 0.0 },
         "mute": { "type": "boolean", "default": false },

app/models/user.py

@@ -5,12 +5,18 @@ import time
 from typing import Optional, Dict, Any, List
 from app.config import settings
 
-DB_PATH = os.path.join(settings.STORAGE_DIR, "sonicforge.db")
+# Default DB lives in storage/; tests override via SONICFORGE_DB_PATH so the
+# dev database is never touched by the test suite.
+DB_PATH = os.getenv("SONICFORGE_DB_PATH") or os.path.join(settings.STORAGE_DIR, "sonicforge.db")
 
 def get_db_connection():
     os.makedirs(settings.STORAGE_DIR, exist_ok=True)
     conn = sqlite3.connect(DB_PATH)
     conn.row_factory = sqlite3.Row
+    # WAL improves concurrent read/write; FK enforcement makes quota/backup
+    # cleanup consistent when users are deleted.
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
     return conn
 
 def init_db():
@@ -65,8 +71,42 @@ def init_db():
     );
     """)
     
+    # Migration: thêm cột backup nếu chưa tồn tại
+    try:
+        cursor.execute("ALTER TABLE projects ADD COLUMN is_backup INTEGER DEFAULT 0")
+    except Exception:
+        pass  # column already exists
+    try:
+        cursor.execute("ALTER TABLE projects ADD COLUMN original_id TEXT DEFAULT NULL")
+    except Exception:
+        pass
+    
+    # Bảng Project Backups (snapshot riêng, không lẫn với projects chính)
+    cursor.execute("""
+    CREATE TABLE IF NOT EXISTS project_backups (
+        id TEXT PRIMARY KEY,
+        user_id TEXT NOT NULL,
+        project_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        data_json TEXT NOT NULL,
+        size_bytes INTEGER DEFAULT 0,
+        created_at REAL NOT NULL,
+        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+    );
+    """)
+    
+    # Placeholder user for anonymous autosave: projects are saved with
+    # user_id='anonymous' when no token is present, so the FK must resolve.
+    cursor.execute("SELECT id FROM users WHERE id = 'anonymous'")
+    if not cursor.fetchone():
+        import secrets as _secrets
+        cursor.execute("""
+        INSERT OR IGNORE INTO users (id, username, email, hashed_password, role, must_change_password, created_at, is_active)
+        VALUES ('anonymous', 'anonymous', 'anonymous@local', ?, 'standard', 0, ?, 0)
+        """, (_secrets.token_hex(32), time.time()))
+    
     conn.commit()
     conn.close()
-
+    
 # Tự động khởi tạo DB khi module được import
 init_db()

app/static/js/services/aiGateway.js

@@ -48,23 +48,27 @@ 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: {
         composition_title: { type: 'string', description: 'Title of the musical piece (e.g., Epic Orchestra Intro 8-Bars)' },
         bpm: { type: 'integer' },
-        total_bars: { type: 'integer' },
+        total_bars: { type: 'integer', description: 'Total length of the composition in bars. You MUST populate all bars with notes.' },
         tracks: {
           type: 'array',
-          description: 'Array of instrument tracks along with their corresponding MIDI notes',
+          description: 'CRITICAL: Array of instrument tracks. You MUST generate exactly the number of tracks requested by the user. Every track in this array MUST contain a full sequence of notes that spans the entire duration of the piece (from start_beat 0.0 to total_bars * 4.0).',
           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',
+                description: 'CRITICAL: Array of MIDI notes. You MUST write notes completely filling all bars from bar 0 (beat 0.0) up to the final bar (beat total_bars * 4.0). Do NOT leave empty bars or stop early. Fill the entire duration of the composition with continuous musical notes.',
                 items: {
                   type: 'object',
                   properties: {
@@ -77,7 +81,7 @@ const AIGateway = (function() {
                 }
               }
             },
-            required: ['track_name', 'instrument_type', 'notes']
+            required: ['track_name', 'instrument_type', 'soundfont_id', 'soundfont_bank', 'soundfont_program', 'notes']
           }
         }
       },
@@ -85,6 +89,197 @@ const AIGateway = (function() {
     }
   }];
 
+  const REARRANGE_TOOL_SPEC = {
+    type: 'function',
+    function: {
+      name: 'rearrange_midi_melody',
+      description: 'Accepts source MIDI notes and rearranges/re-harmonizes them into a new musical variation while preserving the core melody. Use this when the user asks to rearrange, remix, or create variations of an existing MIDI item.',
+      parameters: {
+        type: 'object',
+        properties: {
+          rearrange_title: { type: 'string', description: 'Title/description of the rearranged version (e.g. "Jazz Variation", "Dark Orchestral Remix")' },
+          soundfont_id: { type: 'string', default: 'generaluser_gs' },
+          soundfont_bank: { type: 'integer', default: 0 },
+          soundfont_program: { type: 'integer', default: 0 },
+          rearranged_notes: {
+            type: 'array',
+            description: 'Array of rearranged MIDI notes. Keep the same total_duration_beats as the original unless user explicitly requests length change.',
+            items: {
+              type: 'object',
+              properties: {
+                pitch: { type: 'integer', description: 'MIDI note pitch 0-127 (C4=60)' },
+                start_beat: { type: 'number', description: 'Note start position in beats from 0.0' },
+                duration_beats: { type: 'number', description: 'Note length in beats (quarter=1.0)' },
+                velocity: { type: 'number', description: 'Velocity 0.0-1.0' }
+              },
+              required: ['pitch', 'start_beat', 'duration_beats', 'velocity']
+            }
+          }
+        },
+        required: ['rearrange_title', 'rearranged_notes']
+      }
+    }
+  };
+
+  // ai_midi_rearrange_specification.md §3 — Function Tool Schema hỗ trợ 2 mode:
+  // SIMILAR_VARIATION (biến tấu cùng độ dài) / EXTEND_CONTINUATION (viết tiếp
+  // các bar sau). AI trả gói dữ liệu có vị trí target trên Timeline.
+  const REARRANGE_EXTEND_TOOL_SPEC = {
+    type: 'function',
+    function: {
+      name: 'rearrange_or_extend_midi_melody',
+      description: 'Analyzes source MIDI melody data and returns either a variation (Variation) or continuation (Extend) based on user instructions.',
+      parameters: {
+        type: 'object',
+        properties: {
+          mode: {
+            type: 'string',
+            enum: ['SIMILAR_VARIATION', 'EXTEND_CONTINUATION'],
+            description: "Mode: 'SIMILAR_VARIATION' (new arrangement of equal length) or 'EXTEND_CONTINUATION' (writes subsequent bars)."
+          },
+          composition_title: {
+            type: 'string',
+            description: 'Short title describing the new melody style (e.g., Jazz Swing Variation, Epic Extension Part 2)'
+          },
+          target_start_bar: {
+            type: 'number',
+            description: 'Starting bar number for the generated notes on the Timeline'
+          },
+          target_duration_bars: {
+            type: 'number',
+            description: 'Total bar duration covered by the generated sequence'
+          },
+          soundfont_id: { type: 'string', default: 'generaluser_gs' },
+          soundfont_bank: { type: 'integer', default: 0 },
+          soundfont_program: { type: 'integer', default: 0 },
+          generated_notes: {
+            type: 'array',
+            description: 'Array of AI-generated MIDI notes.',
+            items: {
+              type: 'object',
+              properties: {
+                pitch: { type: 'integer', minimum: 0, maximum: 127 },
+                start_beat: { type: 'number', description: 'Starting beat position relative to beat 0.0 of the generated item' },
+                duration_beats: { type: 'number', minimum: 0.1 },
+                velocity: { type: 'number', minimum: 0.0, maximum: 1.0 }
+              },
+              required: ['pitch', 'start_beat', 'duration_beats', 'velocity']
+            }
+          }
+        },
+        required: ['mode', 'composition_title', 'target_start_bar', 'target_duration_bars', 'generated_notes']
+      }
+    }
+  };
+
+  const REARRANGE_SCENARIOS = [
+    {
+      id: 'arpeggio',
+      keywords: ['arpeggio', 'arp', 'broken chord', 'broken chords', 'shimmering sequence'],
+      description: 'Arpeggio variation',
+      technique: 'Subdivide sustained chord notes (longer than 0.5 beats) into sequential 0.25-beat arpeggiated interval steps using octave/triad jumps. Create a driving, shimmering sequence.'
+    },
+    {
+      id: 'harmonies',
+      keywords: ['harmony', 'harmonize', 'harmonies', '3rd', '3rds', 'duet', 'chord voicing', 'voicing'],
+      description: 'Add parallel harmonies',
+      technique: 'For each source pitch P, insert parallel harmonizing notes at pitch P+3 or P+4 (Major/Minor 3rds) matching the same start_beat. Create richer, fuller texture resembling two instruments playing in duet.'
+    },
+    {
+      id: 'syncopation',
+      keywords: ['syncopation', 'syncopate', 'syncopated', 'off-beat', 'off beat', 'funk', 'latin', 'rnb', 'r&b'],
+      description: 'Syncopation / off-beat feel',
+      technique: 'Shift start_beat alignment off strong beats (0.0, 1.0, 2.0, 3.0) onto off-beats (0.5, 1.5, 2.5, 3.5). Create a rhythmic, syncopated feel.'
+    },
+    {
+      id: 'walking_bass',
+      keywords: ['walking bass', 'bassline', 'bass line', 'walking'],
+      description: 'Walking bass line',
+      technique: 'Lower pitches to bass register (36-48 range). Build continuous quarter-note steps (1.0 beat duration) following the chord outline. Create an improvisational walking bassline.'
+    },
+    {
+      id: 'jazz_swing',
+      keywords: ['jazz', 'swing', 'bebop', 'bop', 'jazz swing'],
+      description: 'Jazz Swing style',
+      technique: 'Apply Jazz Swing characteristics: off-beat syncopation, 7th/9th chord extensions, rhythmic variations, and swung eighth notes (triplet feel). Preserve the core melodic outline while adding jazz harmony.'
+    },
+    {
+      id: 'synthwave',
+      keywords: ['synthwave', '80s', 'retro', 'synth wave', 'outrun', 'retrowave'],
+      description: 'Synthwave / 80s style',
+      technique: 'Transform into 80s Synthwave style: driving 8th-note bass arpeggios, gated reverb snare, analog synth lead with portamento, and pulsating chord pads. Use octave jumps in the bass.'
+    },
+    {
+      id: 'cinematic',
+      keywords: ['cinematic', 'orchestral', 'epic', 'film score', 'movie', 'hollywood', 'symphonic'],
+      description: 'Cinematic Orchestral style',
+      technique: 'Transform into dramatic Cinematic Orchestral style: swelling dynamics, brass stabs on downbeats, string ostinato patterns, taiko percussion hits on strong beats. Layer multiple octaves for epic width.'
+    },
+    {
+      id: 'simplify',
+      keywords: ['simplify', 'minimal', 'strip', 'downbeat', 'reduce', 'sparse'],
+      description: 'Simplify / strip down',
+      technique: 'Keep only the downbeat notes (start_beat at 0.0, 1.0, 2.0, 3.0, etc.). Strip out embellishments, passing tones, and grace notes. Reduce chord voicings to root and 5th only.'
+    },
+    {
+      id: 'passing_tones',
+      keywords: ['passing tone', 'chromatic', 'chromaticism', 'smooth', 'approach note'],
+      description: 'Add passing tones / chromaticism',
+      technique: 'Insert passing tones and chromatic approach notes between chord tones to smooth out the melodic progression. Use half-step and whole-step approach notes targeting chord tones on strong beats.'
+    }
+  ];
+
+  function detectRearrangeScenario(prompt) {
+    if (!prompt) return null;
+    const lower = prompt.toLowerCase();
+    const matched = [];
+    for (const sc of REARRANGE_SCENARIOS) {
+      const hits = sc.keywords.filter(kw => lower.includes(kw.toLowerCase()));
+      if (hits.length > 0) {
+        matched.push({ scenario: sc, hitCount: hits.length });
+      }
+    }
+    matched.sort((a, b) => b.hitCount - a.hitCount);
+    return matched.length > 0 ? matched[0].scenario : null;
+  }
+
+  function buildRearrangeMessage(prompt, sourceContext) {
+    const notesJson = JSON.stringify(sourceContext.notes, null, 2);
+    const scenario = detectRearrangeScenario(prompt);
+    const techniqueSection = scenario
+      ? `\nDETECTED SCENARIO: ${scenario.description}\nSPECIFIC TECHNIQUE REQUIRED: ${scenario.technique}\n`
+      : '';
+
+    const rules = [
+      '1. Use the rearrange_midi_melody tool to return the rearranged notes.',
+      '2. PRESERVE the core melodic outline and overall structure unless the user explicitly asks for a complete transformation.',
+      '3. Keep the total duration (' + sourceContext.total_beats + ' beats) the same unless user requests a different length.',
+      '4. The rearranged_notes array MUST contain notes with pitch (0-127), start_beat (0.0 to ' + sourceContext.total_beats + '.0), duration_beats, and velocity (0.0-1.0).',
+      '5. Start beats should remain within 0-' + sourceContext.total_beats + ' range.',
+      '6. You may add, remove, or modify notes to achieve the requested style.',
+      '7. ALWAYS return a rearrange_title describing what was created (e.g. "Jazz Swing Variation of Piano Lead").'
+    ];
+
+    return [
+      { role: 'system', content: `You are a professional Music Composer & Arranger.
+
+SOURCE MIDI CONTEXT:
+- Track: ${sourceContext.track_name}
+- Item: ${sourceContext.item_name}
+- Duration: ${sourceContext.duration_bars} bars (${sourceContext.total_beats} beats)
+- BPM: ${sourceContext.bpm}
+- Time Signature: 4/4
+- Total notes: ${sourceContext.total_notes}
+
+ORIGINAL MELODY NOTES (pitch, note_name, start_beat, duration_beats, velocity):
+${notesJson}
+${techniqueSection}
+STRICT REARRANGE RULES:
+${rules.join('\n')}` },
+      { role: 'user', content: `${prompt}\n\nRearrange the source MIDI notes above according to this request. Return the result via the rearrange_midi_melody tool.` }
+    ];
+  }
+
   function parseOrigin(urlStr) {
     try { const u = new URL(urlStr); return `${u.protocol}//${u.hostname}${u.port ? ':'+u.port : ''}`; } catch (_) { return null; }
   }
@@ -131,7 +326,10 @@ const AIGateway = (function() {
     } else {
       response = await fetch(`${origin}/api/v1/ai/proxy`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: {
+          'Content-Type': 'application/json',
+          ...(localStorage.getItem('sonic_token') ? { 'X-Auth-Token': localStorage.getItem('sonic_token') } : {})
+        },
         body: JSON.stringify({ url, headers, body })
       });
     }
@@ -176,13 +374,37 @@ 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}
+
+=== HƯỚNG DẪN SOẠN NHẠC MIDI / MIDI COMPOSITION RULES ===
+KHI NGƯỜI DÙNG YÊU CẦU TẠO NHẠC / COMPOSITION RULES:
+1. FULL TRACKS & BARS: If the user requests X tracks and Y bars, you MUST generate exactly X tracks. Each track MUST contain a continuous sequence of MIDI notes starting from beat 0.0 and stretching all the way to beat Y * 4.0 (the end of the composition).
+2. NO EARLY STOPPING: Do NOT stop early or leave empty bars at the end or in the middle. Every track must be fully populated with notes throughout the entire duration.
+3. EXPRESS MELODY & EMOTION: The generated MIDI notes (pitch, start_beat, duration_beats, velocity) must express the requested musical emotion (e.g., happy, sad, epic, energetic, melancholic). Use rich harmonies/chords for backing tracks (Strings, Pads, Piano) and expressive, rhythmic melodies for Lead/Solo tracks. Do NOT write single repeating notes or overly sparse patterns unless explicitly asked.
+4. VIẾT ĐẦY ĐỦ CÁC NOTE: Bạn phải viết đầy đủ các note cho TẤT CẢ các tracks được yêu cầu, và trải dài trong SUỐT chiều dài số bars yêu cầu (ví dụ: yêu cầu 8 bars và 6 tracks thì phải tạo đủ 6 tracks, mỗi track phải có các note MIDI bắt đầu từ beat 0.0 kéo dài liên tục đến beat 32.0 (8 bars * 4 beat/bar)).
+
 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 +421,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 +431,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)) }))
       };
     });
@@ -282,6 +506,11 @@ Ví dụ: "Hãy chọn và copy từ bar 4 đến bar 12 của track 1 sau đó
 
   return {
     DEFAULT_TOOLS,
+    REARRANGE_TOOL_SPEC,
+    REARRANGE_EXTEND_TOOL_SPEC,
+    REARRANGE_SCENARIOS,
+    detectRearrangeScenario,
+    buildRearrangeMessage,
     callLLM,
     extractFunctionCalls,
     buildUserMessage,

app/static/js/services/api.js

@@ -41,6 +41,7 @@ window.API_BASE_URL = window.API_BASE_URL || window.location.origin;
         updateUserQuota: (userId, storageLimitMb, maxTracks = 16) => apiRequest(`/api/v1/admin/quotas/${userId}`, { method: 'PUT', body: JSON.stringify({ storage_limit_mb: storageLimitMb, max_tracks: maxTracks }) }),
         updateUserRole: (userId, role, isActive = true) => apiRequest(`/api/v1/admin/users/${userId}/role`, { method: 'PUT', body: JSON.stringify({ role, is_active: isActive }) }),
         deleteUser: (userId) => apiRequest(`/api/v1/admin/users/${userId}`, { method: 'DELETE' }),
+        createUser: (username, email, password, role = 'standard') => apiRequest('/api/v1/admin/users', { method: 'POST', body: JSON.stringify({ username, email, password, role }) }),
 
         saveTempProject: (dataJson) => apiRequest('/api/v1/projects/temp', { method: 'POST', body: JSON.stringify({ data_json: dataJson }) }),
         getTempProject: () => apiRequest('/api/v1/projects/temp', { method: 'GET' }),
@@ -63,8 +64,18 @@ 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' }),
+        getAIPresets: () => apiRequest('/api/v1/ai/presets', { method: 'GET' }),
+        saveAIPreset: (preset) => apiRequest('/api/v1/ai/presets', { method: 'POST', body: JSON.stringify(preset) }),
+        deleteAIPreset: (presetId) => apiRequest(`/api/v1/ai/presets/${presetId}`, { method: 'DELETE' }),
+
+        createBackup: (projectId) => apiRequest(`/api/v1/projects/cloud/${projectId}/backup`, { method: 'POST' }),
+        listBackups: (projectId) => apiRequest(`/api/v1/projects/cloud/${projectId}/backups`, { method: 'GET' }),
+        deleteBackup: (backupId) => apiRequest(`/api/v1/projects/cloud/backups/${backupId}`, { method: 'DELETE' }),
+        cleanupBackups: (keep) => apiRequest('/api/v1/projects/cloud/backups/cleanup', { method: 'POST', body: JSON.stringify({ keep }) }),
+
         renderProject: (projectJson, outputFilename) => apiRequest('/api/v1/plugins/render', { method: 'POST', body: JSON.stringify({ project_json: projectJson, output_filename: outputFilename }) }),
         deleteSoundFont: (sfId) => apiRequest(`/api/v1/plugins/soundfont/${sfId}`, { method: 'DELETE' }),
         uploadSoundFont: async (file) => {

app/static/js/services/dawCommandDispatcher.js

@@ -72,6 +72,7 @@ const DAWCommandDispatcher = (function() {
     register('MODIFY_MIDI_NOTES', (args) => api.modifyMidiNotes(args));
     register('PROCESS_AI_DSP', (args) => api.processAudioDsp(args));
     register('GENERATE_MULTITRACK_MIDI', (args) => api.generateMultitrackMidi(args));
+    register('REARRANGE_MIDI_MELODY', (args) => api.rearrangeMidiMelody(args));
   }
 
   return {

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/ghostNoteExtractor.js

@@ -0,0 +1,77 @@
+// SonicForge Studio Ghost Note Extractor Service
+(function() {
+  function extractGhostLayers(activeTracks, targetTrackId, targetItemId, bpm) {
+    if (!activeTracks || !targetItemId) return [];
+
+    const secondsPerBeat = 60.0 / (parseInt(bpm) || 120);
+
+    let targetItem = null;
+    for (var i = 0; i < activeTracks.length; i++) {
+      var t = activeTracks[i];
+      var found = (t.midiItems || []).find(function(m) { return m.id === targetItemId; });
+      if (found) { targetItem = found; break; }
+    }
+    if (!targetItem) return [];
+
+    const windowStartBeat = targetItem.startTime / secondsPerBeat;
+    const windowEndBeat = (targetItem.startTime + targetItem.duration) / secondsPerBeat;
+
+    const ghostLayers = [];
+
+    for (var i = 0; i < activeTracks.length; i++) {
+      var track = activeTracks[i];
+      if (!track.midiItems || !track.midiItems.length) continue;
+      if (track.muted) continue;
+
+      var isSameTrack = track.id === targetTrackId;
+      var trackGhostNotes = [];
+
+      for (var j = 0; j < track.midiItems.length; j++) {
+        var item = track.midiItems[j];
+        if (item.id === targetItemId) continue;
+
+        var itemStartBeat = item.startTime / secondsPerBeat;
+        var itemEndBeat = (item.startTime + item.duration) / secondsPerBeat;
+
+        // Same-track items always contribute notes (show whole track); cross-track only when overlapping the window
+        if (itemStartBeat >= windowEndBeat || itemEndBeat < windowStartBeat) {
+          if (!isSameTrack) continue;
+        }
+
+        var notes = item.notes || [];
+        for (var k = 0; k < notes.length; k++) {
+          var note = notes[k];
+          var noteAbsStart = itemStartBeat + (note.start_beat || 0);
+          var noteAbsEnd = noteAbsStart + (note.duration_beats || 1);
+
+          if (noteAbsStart >= windowEndBeat && !isSameTrack) continue;
+
+          trackGhostNotes.push({
+            id: 'ghost_' + (note.id || Math.random().toString(36).substr(2, 9)),
+            pitch: note.pitch,
+            relative_start_beat: noteAbsStart - windowStartBeat,
+            duration_beats: (note.duration_beats || 1),
+            velocity: note.velocity,
+            item_id: item.id,
+            original_track_name: track.name,
+            original_track_color: track.color || '#888888'
+          });
+        }
+      }
+
+      if (trackGhostNotes.length > 0) {
+        ghostLayers.push({
+          track_id: track.id,
+          track_name: track.name,
+          track_color: track.color || '#6b7280',
+          isSameTrack: isSameTrack,
+          notes: trackGhostNotes
+        });
+      }
+    }
+
+    return ghostLayers;
+  }
+
+  window.SonicGhost = { extractGhostLayers: extractGhostLayers };
+})();

app/static/js/services/midiExtractor.js

@@ -0,0 +1,60 @@
+const SonicMidiExtractor = (function() {
+  const NOTE_NAMES = ['C','C#','D','D#','E','F','F#','G','G#','A','A#','B'];
+
+  function midiPitchToNoteName(pitch) {
+    const note = NOTE_NAMES[pitch % 12];
+    const octave = Math.floor(pitch / 12) - 1;
+    return note + octave;
+  }
+
+  function extractSelectedMIDIContext(tracks, selectedItemId, bpm) {
+    let targetItem = null;
+    let targetTrack = null;
+
+    for (const track of tracks) {
+      const items = track.midiItems || [];
+      const item = items.find(i => i.id === selectedItemId);
+      if (item) { targetItem = item; targetTrack = track; break; }
+    }
+
+    if (!targetItem) {
+      throw new Error('Please select a MIDI Item on the Timeline before requesting a Rearrangement!');
+    }
+
+    const notes = targetItem.notes || [];
+    if (notes.length === 0) {
+      throw new Error('Selected MIDI item has no notes to rearrange.');
+    }
+
+    const compactNotes = notes.map(n => ({
+      pitch: n.pitch,
+      note_name: midiPitchToNoteName(n.pitch),
+      start_beat: parseFloat((n.start_beat || 0).toFixed(2)),
+      duration_beats: parseFloat((n.duration_beats || 1).toFixed(2)),
+      velocity: parseFloat((n.velocity || 0.8).toFixed(2))
+    }));
+
+    const totalDurationBeats = compactNotes.reduce((max, n) => Math.max(max, n.start_beat + n.duration_beats), 0);
+
+    return {
+      track_name: targetTrack.name,
+      track_id: targetTrack.id,
+      item_id: targetItem.id,
+      item_name: targetItem.name,
+      duration_bars: targetItem.length_bars || Math.ceil(totalDurationBeats / 4),
+      total_beats: Math.ceil(totalDurationBeats),
+      bpm: parseInt(bpm || '120'),
+      total_notes: compactNotes.length,
+      notes: compactNotes,
+      instrument: targetTrack.synth_engine ? {
+        soundfont_id: targetTrack.synth_engine.soundfont_id || '',
+        soundfont_bank: targetTrack.synth_engine.soundfont_bank ?? 0,
+        soundfont_program: targetTrack.synth_engine.soundfont_program ?? 0
+      } : null
+    };
+  }
+
+  return { extractSelectedMIDIContext, midiPitchToNoteName };
+})();
+
+window.SonicMidiExtractor = SonicMidiExtractor;

app/static/js/services/pianoRollTabService.js

@@ -0,0 +1,43 @@
+(function () {
+    'use strict';
+    window.SonicPianoRoll = {
+        getParentTrackByItemId: function (itemId, tracks) {
+            if (!tracks || !itemId) return null;
+            for (var i = 0; i < tracks.length; i++) {
+                var items = tracks[i].midiItems || [];
+                for (var j = 0; j < items.length; j++) {
+                    if (items[j].id === itemId) return tracks[i];
+                }
+            }
+            return null;
+        },
+        getParentTrackIdByItemId: function (itemId, tracks) {
+            var trk = this.getParentTrackByItemId(itemId, tracks);
+            return trk ? trk.id : null;
+        },
+        buildActiveScope: function (itemId, tracks) {
+            var parentTrack = this.getParentTrackByItemId(itemId, tracks);
+            if (!parentTrack) return null;
+            var trackIndex = -1;
+            for (var i = 0; i < tracks.length; i++) {
+                if (tracks[i].id === parentTrack.id) { trackIndex = i; break; }
+            }
+            return {
+                item_id: itemId,
+                parent_track_id: parentTrack.id,
+                midi_channel: trackIndex >= 0 ? trackIndex % 16 : 0,
+                current_synth_engine: parentTrack.synth_engine || null,
+                instrument_program: parentTrack.instrumentProgram,
+                instrument_name: parentTrack.instrumentName
+            };
+        },
+        getTrackMidiChannel: function (track, tracks) {
+            if (track && track.midiChannel !== undefined) return track.midiChannel;
+            if (!track || !tracks) return 0;
+            for (var i = 0; i < tracks.length; i++) {
+                if (tracks[i].id === track.id) return i % 16;
+            }
+            return 0;
+        }
+    };
+})();

app/static/js/services/promptTemplateManager.js

@@ -0,0 +1,261 @@
+const PromptTemplateManager = (function() {
+  const DEFAULT_PRESETS = [
+    {
+      id: "preset_epic_orchestra_intro",
+      name: "Epic Orchestra Intro (8 Bars)",
+      keywords: ["epic orchestra", "epic orchestral", "hoành tráng", "nhạc phim epic"],
+      category: "Orchestral / Film Score",
+      default_bars: 8,
+      default_bpm: 130,
+      default_scale: "C Minor",
+      system_instruction_template: "You are a professional film composer. Create a powerful, dramatic 8-bar orchestral intro. Write notes continuously across all 8 bars (from beat 0.0 to 32.0) for every track. Use whole notes, half notes, or quarter notes to maintain a clean layout without overloading the sequence. The required structure to return via the `generate_multitrack_midi` tool consists of 3 tracks: 1. Strings: plays smooth legato chord changes (one chord per 1 or 2 bars continuously). 2. Brass Theme: plays a swelling simple melodic line in the C3-C5 range spanning all 8 bars. 3. Epic Percussion: hits heavily on beats 1 and 3 throughout the entire 8 bars.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-23T16:00:00Z"
+    },
+    {
+      id: "preset_pop_piano_chords",
+      name: "Pop Piano Chords (4 Bars)",
+      keywords: ["pop piano", "piano chords", "ballad piano", "hợp âm piano"],
+      category: "Pop / Ballad",
+      default_bars: 4,
+      default_bpm: 90,
+      default_scale: "C Major",
+      system_instruction_template: "You are a professional Pop Piano player. Generate a beautiful 4-bar piano chord progression (e.g. C - G - Am - F) with pleasant chord voicing and simple accompaniment. Return the MIDI notes via the `generate_multitrack_midi` function on a track named 'Pop Piano'. Write notes continuously across all 4 bars (from beat 0.0 to 16.0). Use whole/half/quarter notes continuously to ensure every bar has piano chords playing.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-23T16:00:00Z"
+    },
+    {
+      id: "preset_cyberpunk_synth",
+      name: "Cyberpunk Synthwave (8 Bars)",
+      keywords: ["cyberpunk synth", "synthwave", "cyberpunk", "futuristic synth"],
+      category: "Electronic / Synthwave",
+      default_bars: 8,
+      default_bpm: 120,
+      default_scale: "A Minor",
+      system_instruction_template: "You are a Synthwave producer. Generate a driving 8-bar cyberpunk synth theme. Return MIDI notes via `generate_multitrack_midi` containing: 1. Synth Bass: plays eighth notes on pitch A1, C2, G1 continuously across all 8 bars (from beat 0.0 to 32.0). 2. Synth Lead: plays a simple, melodic line in the high register (C4-E5) continuously across all 8 bars (from beat 0.0 to 32.0).",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-23T16:00:00Z"
+    },
+    // ── Rearrange & Variation Scenarios ──
+    {
+      id: "preset_rearrange_arpeggio",
+      name: "Arpeggio Variation",
+      keywords: ["arpeggio", "arp", "broken chord", "arpeggiate"],
+      category: "Rearrange / Variation",
+      default_bars: 8,
+      default_bpm: 120,
+      default_scale: "C Major",
+      system_instruction_template: "You are a professional arranger. Rearrange the source MIDI notes into an arpeggiated variation. Subdivide sustained chord notes into sequential 0.25-beat arpeggiated steps with octave/triad jumps. Create a driving, shimmering sequence while preserving the underlying chord progression.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-28T11:00:00Z"
+    },
+    {
+      id: "preset_rearrange_harmonies",
+      name: "Add 3rd/4th Harmonies",
+      keywords: ["harmony", "harmonize", "harmonies", "3rd", "duet", "chord voicing"],
+      category: "Rearrange / Variation",
+      default_bars: 8,
+      default_bpm: 120,
+      default_scale: "C Major",
+      system_instruction_template: "You are a professional arranger. Add parallel harmonizing notes to the source melody. For each source pitch P, insert notes at P+3 or P+4 (Major/Minor 3rds) at the same start_beat. Create a richer, fuller texture resembling two instruments playing in duet.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-28T11:00:00Z"
+    },
+    {
+      id: "preset_rearrange_syncopation",
+      name: "Syncopation / Off-beat",
+      keywords: ["syncopation", "syncopate", "syncopated", "off-beat", "off beat", "funk", "latin"],
+      category: "Rearrange / Variation",
+      default_bars: 8,
+      default_bpm: 120,
+      default_scale: "C Major",
+      system_instruction_template: "You are a professional arranger. Apply syncopation to the source melody. Shift start_beat alignment off strong beats (0.0, 1.0, 2.0, 3.0) onto off-beats (0.5, 1.5, 2.5, 3.5). Preserve the core melodic outline while creating a rhythmic, syncopated feel.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-28T11:00:00Z"
+    },
+    {
+      id: "preset_rearrange_walking_bass",
+      name: "Walking Bass Line",
+      keywords: ["walking bass", "bassline", "walking"],
+      category: "Rearrange / Variation",
+      default_bars: 8,
+      default_bpm: 120,
+      default_scale: "C Major",
+      system_instruction_template: "You are a professional arranger. Transform the source melody into a walking bass line. Lower pitches to bass register (36-48 range). Build continuous quarter-note steps following the chord outline. Create an improvisational walking bassline matching the original chord progression.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-28T11:00:00Z"
+    },
+    {
+      id: "preset_rearrange_jazz",
+      name: "Jazz Swing Rearrangement",
+      keywords: ["jazz", "swing", "jazz swing", "bebop"],
+      category: "Rearrange / Variation",
+      default_bars: 8,
+      default_bpm: 120,
+      default_scale: "C Major",
+      system_instruction_template: "You are a professional Jazz arranger. Rearrange the source melody into a rhythmic Jazz Swing style. Apply: off-beat syncopation, 7th/9th chord extensions, swung eighth notes (triplet feel), and rhythmic variations while preserving the core melodic outline.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-28T11:00:00Z"
+    },
+    {
+      id: "preset_rearrange_synthwave",
+      name: "Synthwave / 80s Style",
+      keywords: ["synthwave", "80s", "retro", "synth wave", "retrowave", "outrun"],
+      category: "Rearrange / Variation",
+      default_bars: 8,
+      default_bpm: 120,
+      default_scale: "A Minor",
+      system_instruction_template: "You are a Synthwave producer. Transform the source melody into an 80s Synthwave style. Apply: driving 8th-note bass arpeggios, analog synth lead with portamento, pulsating chord pads, and octave jumps in the bass.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-28T11:00:00Z"
+    },
+    {
+      id: "preset_rearrange_cinematic",
+      name: "Cinematic Orchestral",
+      keywords: ["cinematic", "orchestral", "epic", "film score", "symphonic", "hollywood"],
+      category: "Rearrange / Variation",
+      default_bars: 8,
+      default_bpm: 130,
+      default_scale: "C Minor",
+      system_instruction_template: "You are a cinematic composer. Transform the source melody into a dramatic Cinematic Orchestral arrangement. Apply: swelling dynamics, brass stabs on downbeats, string ostinato patterns, taiko percussion hits. Layer multiple octaves for epic width.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-28T11:00:00Z"
+    },
+    {
+      id: "preset_rearrange_simplify",
+      name: "Simplify / Strip Down",
+      keywords: ["simplify", "minimal", "strip down", "sparse", "reduce"],
+      category: "Rearrange / Variation",
+      default_bars: 8,
+      default_bpm: 120,
+      default_scale: "C Major",
+      system_instruction_template: "You are a professional arranger. Simplify the source melody: keep only downbeat notes (start_beat at 0.0, 1.0, 2.0, 3.0). Strip out embellishments, passing tones, and grace notes. Reduce chord voicings to root and 5th only.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-28T11:00:00Z"
+    },
+    {
+      id: "preset_rearrange_chromatic",
+      name: "Passing Tones & Chromaticism",
+      keywords: ["passing tone", "chromatic", "chromaticism", "smooth", "approach note"],
+      category: "Rearrange / Variation",
+      default_bars: 8,
+      default_bpm: 120,
+      default_scale: "C Major",
+      system_instruction_template: "You are a professional arranger. Add passing tones and chromatic approach notes to the source melody. Insert half-step and whole-step approach notes targeting chord tones on strong beats. Smooth out the melodic progression while preserving the harmonic framework.",
+      is_user_defined: false,
+      is_favorite: false,
+      created_at: "2026-07-28T11:00:00Z"
+    }
+  ];
+
+  const STORAGE_KEY = 'daw_ai_prompt_presets';
+
+  function PromptTemplateManager() {
+    this.presets = [];
+    this.loadPresets();
+  }
+
+  PromptTemplateManager.prototype.loadPresets = function() {
+    try {
+      const localData = localStorage.getItem(STORAGE_KEY);
+      if (localData) {
+        const parsed = JSON.parse(localData);
+        const userPresets = parsed.filter(p => p.is_user_defined);
+        this.presets = [...DEFAULT_PRESETS, ...userPresets];
+      } else {
+        this.presets = [...DEFAULT_PRESETS];
+        this.savePresets();
+      }
+    } catch (_) {
+      this.presets = [...DEFAULT_PRESETS];
+    }
+  };
+
+  PromptTemplateManager.prototype.savePresets = function() {
+    const userData = this.presets.filter(p => p.is_user_defined);
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(userData));
+  };
+
+  PromptTemplateManager.prototype.getPresets = function() {
+    return this.presets;
+  };
+
+  PromptTemplateManager.prototype.matchPreset = function(userQuery) {
+    if (!userQuery) return null;
+    const queryLower = userQuery.toLowerCase();
+    let bestMatch = null;
+    let bestScore = 0;
+
+    for (const preset of this.presets) {
+      for (const kw of preset.keywords) {
+        const kwLower = kw.toLowerCase();
+        if (queryLower === kwLower) {
+          if (3 > bestScore) {
+            bestScore = 3;
+            bestMatch = { preset, score: 3 };
+          }
+        } else if (queryLower.includes(kwLower)) {
+          if (2 > bestScore) {
+            bestScore = 2;
+            bestMatch = { preset, score: 2 };
+          }
+        } else if (kwLower.includes(queryLower)) {
+          if (1 > bestScore) {
+            bestScore = 1;
+            bestMatch = { preset, score: 1 };
+          }
+        }
+      }
+    }
+    return bestMatch;
+  };
+
+  PromptTemplateManager.prototype.saveUserPreset = function(presetObject) {
+    const index = this.presets.findIndex(p => p.id === presetObject.id);
+    if (index >= 0) {
+      this.presets[index] = presetObject;
+    } else {
+      this.presets.push(presetObject);
+    }
+    this.savePresets();
+  };
+
+  PromptTemplateManager.prototype.deletePreset = function(id) {
+    this.presets = this.presets.filter(p => p.id !== id);
+    this.savePresets();
+  };
+
+  PromptTemplateManager.prototype.getContextualSuggestions = function(hasSelectedItem) {
+    if (hasSelectedItem) {
+      return this.presets.filter(p => p.category === 'Rearrange / Variation' || p.is_favorite);
+    } else {
+      return this.presets.filter(p => p.category !== 'Rearrange / Variation');
+    }
+  };
+
+  PromptTemplateManager.prototype.toggleFavorite = function(id) {
+    const preset = this.presets.find(p => p.id === id);
+    if (preset) {
+      preset.is_favorite = !preset.is_favorite;
+      if (preset.is_user_defined) {
+        this.savePresets();
+      }
+    }
+  };
+
+  return PromptTemplateManager;
+})();
+
+window.PromptTemplateManager = PromptTemplateManager;
+window.DEFAULT_PRESETS = (new PromptTemplateManager()).getPresets();

app/static/js/services/soundfontPlayer.js

@@ -1,18 +1,52 @@
-// SonicForge Studio SoundFont Player Service
 (function () {
-    'use strict';
+    const RENDER_BLOCK = 512;
+    const QUEUE_TARGET = 16;
+    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 _pendingOutputDestination = null;
+    let _outputDestination = null; // cache đích route — dedupe swap dư giữa stream
+    let _validPercCache = {};      // { sfId: [bank, prog] | null } — preset percussion hợp lệ
+    let _sfLoadFailAt = {};        // { sfId: timestamp } — cooldown 10s sau load fail
+    let _scheduledNotes = [];
+    let _loadPromises = {};
+    let _sfloadSeq = 0;
 
-    const activeOscillators = {};
-
-    // Use the shared AudioContext from the main app (lazy init)
-    let __gainNode = null;
-    const getCtx = () => {
+    const getCtx = function () {
+        if (_audioCtx) {
+            if (!_gainNode) {
+                _gainNode = _audioCtx.createGain();
+                _gainNode.gain.value = 0.3;
+                _outputDestination = _pendingOutputDestination || (window.masterBus ? window.masterBus.input : _audioCtx.destination);
+                _gainNode.connect(_outputDestination);
+            }
+            return _audioCtx;
+        }
         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;
+                _outputDestination = _pendingOutputDestination || (window.masterBus ? window.masterBus.input : ctx.destination);
+                _gainNode.connect(_outputDestination);
             }
             return ctx;
         }
@@ -22,172 +56,730 @@
         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;
+            _outputDestination = _pendingOutputDestination || window.__sharedAudioCtx.destination;
+            _gainNode.connect(_outputDestination);
         }
         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;
+        // Route the shared FluidSynth output through a per-track node (e.g. the
+        // track's gainNode) so the track's FX chain / fader / pan affect the
+        // soundfont instrument. Pass null to restore the default master-bus route.
+        setOutputDestination: function (node) {
+            try {
+                if (_gainNode) {
+                    const dest = node || (window.masterBus ? window.masterBus.input : ((_audioCtx || window.__sharedAudioCtx).destination));
+                    // DEDUPE: đích không đổi → KHÔNG disconnect/reconnect.
+                    // Swap dư giữa dòng notes đang phát (applyAllTrackMuteSolo →
+                    // updateSfRouting gọi lại cùng đích sfEntry sau noteon đầu)
+                    // làm ScriptProcessor xuất buffer uninitialized → NaN →
+                    // 11 biquad "state is bad" → CÂM (mọi log: state-bad nổ
+                    // ngay sau setOutputDestination lần 2).
+                    if (dest === _outputDestination) return;
+                    _gainNode.disconnect();
+                    _gainNode.connect(dest);
+                    // Reconnect VU analyser tap (app.jsx VU tick gắn __vuAnalyser
+                    // trên _gainNode): disconnect() không đối số ngắt MỌI kết
+                    // nối kể cả analyser → sfAudioPeak = 0 mãi → track VU MIDI
+                    // không nhảy khi có âm (user bug 06:35).
+                    if (_gainNode.__vuAnalyser) _gainNode.connect(_gainNode.__vuAnalyser);
+                    _outputDestination = dest;
+                    console.log('[SonicSF] setOutputDestination to:', node ? 'track node (sfEntry)' : 'masterBus.input');
+                } else {
+                    _pendingOutputDestination = node || null;
+                    console.log('[SonicSF] setOutputDestination pending:', node ? 'track node (sfEntry)' : 'null');
+                }
+            } catch (e) {
+                console.warn('[SonicSF] setOutputDestination error:', e);
+            }
+        },
+        getOutputNode: function () {
+            return _gainNode;
         },
 
-        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;
+        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();
+                    // Create gain node for master bus routing before any node connections
+                    if (!_gainNode) {
+                        _gainNode = _audioCtx.createGain();
+                        _gainNode.gain.value = 0.3;
+                        _outputDestination = _pendingOutputDestination || (window.masterBus ? window.masterBus.input : _audioCtx.destination);
+                        _gainNode.connect(_outputDestination);
+                    }
 
-            const osc = ctx.createOscillator();
-            const noteGain = ctx.createGain();
+                    console.log("[SonicSF] AudioCtx state:", _audioCtx.state, "sampleRate:", _audioCtx.sampleRate);
 
-            // 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;
+                    // ── Renderer selection ──
+                    // ScriptProcessor is the default and FINAL choice: it is
+                    // pull-based (onaudioprocess is invoked by the audio thread),
+                    // so it cannot starve when the main thread is busy (font
+                    // loading, WASM decode, UI). The AudioWorklet push model
+                    // (setInterval on the main thread) starves under load and
+                    // produces SILENCE on this machine — repeatedly confirmed.
+                    // The deprecation console warning is purely cosmetic.
+                    var _useScriptNode = true;
+                    try {
+                        await _audioCtx.audioWorklet.addModule('/static/js/worklets/fluidsynth-bridge.js?v=202608031240');
+                        console.log("[SonicSF] Worklet registered OK (unused)");
+                    } catch (e) {
+                        console.warn("[SonicSF] Worklet reg failed:", e);
+                    }
 
-            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;
+                    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) {
+                            // "No preset found on channel" is FluidSynth's
+                            // expected notice when a soundfont simply has no
+                            // preset for a bank (e.g. bank 128 on a melodic-only
+                            // font) — the note is just silent, not an error.
+                            if (msg && (msg.indexOf('No preset found on channel') !== -1 || msg.indexOf('There is no preset with bank number') !== -1)) return;
+                            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", 1.0);
+                    _fluidModule._fluid_settings_setnum(_settingsPtr, "synth.polyphony", 256);
+                    _fluidModule._fluid_settings_setint(_settingsPtr, "synth.verbose", 0);
+                    _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 {
+                            // Force stereo output regardless of the device's
+                            // channel count — FluidSynth renders stereo, and a
+                            // mono output would crash the worklet (out[1] undefined).
+                            _workletNode = new AudioWorkletNode(_audioCtx, 'fluidsynth-bridge', {
+                                numberOfOutputs: 1,
+                                outputChannelCount: [2],
+                                channelCount: 2,
+                                channelCountMode: 'explicit'
+                            });
+                            _workletNode.connect(_gainNode);
+                            console.log("[SonicSF] AudioWorklet node connected via gain");
+                            _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);
+                        // Heap WASM có thể realloc khi load SoundFont lớn (SGM-V2.01
+                        // ~300MB) → lp/rp DANGLE → đọc vùng nhớ đã free → NaN/garbage
+                        // → master chain "state is bad" → CÂM + stuck. Theo dõi
+                        // buffer + re-malloc khi đổi.
+                        var _heapBufRef = _fluidModule.HEAPU8.buffer;
+                        spn.onaudioprocess = function (e) {
+                            var left = e.outputBuffer.getChannelData(0);
+                            var right = e.outputBuffer.getChannelData(1);
+                            var sz = left.length;
+                            try {
+                                if (_fluidModule.HEAPU8.buffer !== _heapBufRef) {
+                                    try { _fluidModule._free(lp); _fluidModule._free(rp); } catch (er2) {}
+                                    lp = _fluidModule._malloc(sz * 4);
+                                    rp = _fluidModule._malloc(sz * 4);
+                                    _heapBufRef = _fluidModule.HEAPU8.buffer;
+                                }
+                                _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++) {
+                                    // NaN sweep: mẫu NaN/Inf → 0 (chain biquad
+                                    // KHÔNG BAO GIỜ được nhận NaN → không state-bad).
+                                    var L = hf[lpb + si], R = hf[rpb + si];
+                                    left[si] = isFinite(L) ? L : 0;
+                                    right[si] = isFinite(R) ? R : 0;
+                                }
+                            } catch (er) {}
+                        };
+                        spn.connect(_gainNode);
+                        _workletNode = spn;
+                        console.log("[SonicSF] ScriptProcessorNode connected via gain (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;
+        },
+
+        _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 + '_' + (++_sfloadSeq) + '_' + Date.now();
+            try { _fluidModule.FS.unlink(fname); } catch (e) {}
+            _fluidModule.FS.writeFile(fname, new Uint8Array(buf));
+            var cPath = this._allocCStr(fname);
+            // reset_presets = 0: loading a NEW soundfont must NOT reset the
+            // presets already selected on other channels. With 1, FluidSynth
+            // re-points every channel to the new font's preset 0, so loading a
+            // second instrument silently changes the first one's sound
+            // (decay/loop envelope…).
+            var handle = _fluidModule._fluid_synth_sfload(_synthPtr, cPath, 0);
+            _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;
+            }
+            // Deduplicate concurrent loads: rapid key presses (or several armed
+            // tracks) all call loadSoundFont for the same font before the first
+            // load resolves. Without this, the same soundfont is sfload'd several
+            // times (handles 1,2,3,4…) — wasting the 256MB WASM heap and stalling
+            // notes until each load finishes (audible lag, then silence).
+            if (!_loadPromises[sfId]) {
+                _loadPromises[sfId] = this._doLoadSoundFont(sfId).then(function (ok) {
+                    // Do NOT cache failures: a transient error (network hiccup,
+                    // memory pressure) must not permanently kill the instrument —
+                    // the next note retries the load and recovers.
+                    if (!ok) delete _loadPromises[sfId];
+                    return ok;
+                });
+            }
+            return _loadPromises[sfId];
+        },
+
+        _doLoadSoundFont: async function (sfId) {
+            try {
+                // KHÔNG unload SF cũ khi sfload SF mới: unload làm handle cũ
+                // thành rác trong khi channel state vẫn trỏ tới → program_select
+                // bị skip (progAlreadySet) → noteon trên handle đã unload →
+                // "Instrument not found ... substituted prog 0". Heap 256MB đủ
+                // cho vài SF (SGM + latin = 2 handle — log OK). SF cũ khi cần
+                // lại chỉ được sfload lại nếu map bị xóa (không xảy ra ở đây).
+                var cache = window.SonicSFStorage;
+                var buf = cache ? await cache.getBuffer(sfId) : null;
+                if (buf) {
+                    var cachedOk = this._tryLoadSFL(buf, '.sf3');
+                    if (cachedOk === -1) cachedOk = this._tryLoadSFL(buf, '.sf2');
+                    if (cachedOk !== -1) {
+                        _sfHandleMap.set(sfId, cachedOk);
+                        _currentSfId = sfId;
+                        _loadedFonts[sfId] = true;
+                        console.log("[SonicSF] SoundFont loaded from cache:", sfId, "handle:", cachedOk);
+                        return true;
+                    }
+                    // Stale/corrupt cache (e.g. old SF3 buffers the WASM can't
+                    // decode) — drop it and re-download from the server.
+                    console.warn("[SonicSF] Cached SoundFont unplayable, re-downloading:", sfId);
+                    try { await cache.saveBuffer(sfId, null); } catch (e2) {}
+                }
+                var url = "/api/v1/plugins/soundfonts/download/" + encodeURIComponent(sfId) + "?t=" + Date.now();
+                var resp = await fetch(url);
+                if (!resp.ok) {
+                    // Fallback: font bundled theo deployment (static/soundfonts —
+                    // serve qua /soundfonts/{f} — catalog default-soundfonts).
+                    var url2 = "/soundfonts/" + encodeURIComponent(sfId.replace(/^sf_/, '')) + "?t=" + Date.now();
+                    var resp2 = await fetch(url2);
+                    if (!resp2.ok) {
+                        console.warn("[SonicSF] SoundFont not found:", sfId);
+                        return false;
+                    }
+                    resp = resp2;
+                }
+                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 = (typeof getAudioContext === 'function') ? getAudioContext() : 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 (channel === undefined || channel === null) {
+                if (!_engineChMap[engKey]) {
+                    var allocCh = this.allocateChannel(bank);
+                    _engineChMap[engKey] = allocCh;
+                    channel = allocCh;
+                } else {
+                    channel = _engineChMap[engKey];
+                }
+            } else if (!_engineChMap[engKey]) {
+                _engineChMap[engKey] = channel;
+            }
+            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);
+            _channels[channel].sfId = sfId;
+        },
+
+        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 = (typeof getAudioContext === 'function') ? getAudioContext() : 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 parsedPitch = parseInt(note);
+            var midiPitch = isNaN(parsedPitch) ? 60 : Math.min(127, Math.max(0, parsedPitch));
+            var rawVel = (typeof velocity === 'number' && isFinite(velocity)) ? (velocity > 1 ? velocity : velocity * 127) : 100;
+            if (isNaN(rawVel)) rawVel = 100;
+            var midiVel = Math.min(127, Math.max(1, Math.floor(rawVel)));
+            var _origChannel = channel;
+            var usedBank = 0, usedProg = 0;
+            if (synthEngine) {
+                usedBank = synthEngine.soundfont_bank || 0;
+                usedProg = synthEngine.soundfont_program || 0;
+                if (channel === undefined) {
+                    var engKey = (synthEngine.soundfont_id || '') + ':' + usedBank + ':' + usedProg;
+                    var mappedCh = _engineChMap[engKey];
+                    if (mappedCh !== undefined) {
+                        channel = mappedCh;
+                    } else {
+                        channel = usedBank === 128 ? 9 : 0;
+                    }
+                }
+                if (channel === undefined) channel = (usedBank === 128 ? 9 : 0);
+            } else if (program !== undefined) {
+                usedProg = program;
+                if (channel === undefined) channel = 0;
+            } else {
+                // No instrument configured: silent — no FluidSynth, no oscillator.
+                return;
+            }
+            if (channel === undefined) channel = (usedBank === 128 ? 9 : 0);
+            var ch = channel;
+            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 {
+                    var finalBank = parseInt(usedBank);
+                    if (isNaN(finalBank) || !isFinite(finalBank)) finalBank = 0;
+                    var finalProg = parseInt(usedProg);
+                    if (isNaN(finalProg) || !isFinite(finalProg)) finalProg = 0;
+                    var finalSfId = synthEngine ? synthEngine.soundfont_id : undefined;
+                    var cachedCh = _channels[ch];
+                    // The note's own synth engine (track instrument) is
+                    // authoritative. Channel state is only a cache: it must never
+                    // mask the track's instrument, otherwise multi-track ARM or a
+                    // re-picked instrument plays the wrong soundfont. Without an
+                    // engine, fall back to the soundfont configured on the channel.
+                    if (!synthEngine && cachedCh && cachedCh.sfId !== undefined) {
+                        finalBank = parseInt(cachedCh.bank) || 0;
+                        finalProg = parseInt(cachedCh.program) || 0;
+                        finalSfId = cachedCh.sfId;
+                    }
+                    // Ensure the soundfont is actually loaded before the note plays.
+                    // Quick instrument pick on a track does not pre-load it, so load
+                    // lazily here and retry the note once the font is ready.
+                    if (finalSfId && !_sfHandleMap.has(finalSfId)) {
+                        // Cooldown lỗi: font 404 → KHÔNG spam fetch mỗi note (10s)
+                        // — note chạy thẳng fallback để CÓ ÂM.
+                        var _lastFail = _sfLoadFailAt[finalSfId] || 0;
+                        if (Date.now() - _lastFail < 10000) {
+                            try { self._playNoteFallback(note, velocity, durationMs, startTime, program, null, channel, synthEngine); } catch (e) {}
+                            return;
+                        }
+                        console.log('[SonicSF] soundfont not loaded yet, loading:', finalSfId);
+                        self.loadSoundFont(finalSfId).then(function (ok) {
+                            console.log('[SonicSF] loadSoundFont result:', ok, 'for:', finalSfId);
+                            if (ok) {
+                                doNote();
+                            } else {
+                                // Font KHÔNG tải được (404/format) → KHÔNG drop note
+                                // câm lặng ("bỏ qua WASM") — fallback oscillator.
+                                _sfLoadFailAt[finalSfId] = Date.now();
+                                try { self._playNoteFallback(note, velocity, durationMs, startTime, program, null, channel, synthEngine); } catch (e) {}
+                            }
+                        });
+                        return;
+                    }
+                    // Program change at note time, not call time — ensures correct
+                    // instrument for each item regardless of processing order.
+                    // Skip if the channel already has this exact instrument (avoids
+                    // per-note soundfont reloads that cause audible crackle/glitches).
+                    // ⚠️ Chỉ skip khi handle SF vẫn CÒN HỢP LỆ trong map — nếu
+                    // không → vẫn program_select lại (tránh dùng handle đã unload).
+                    var progAlreadySet = cachedCh && cachedCh.program === finalProg && cachedCh.bank === finalBank && cachedCh.sfId === finalSfId
+                        && (finalSfId ? _sfHandleMap.has(finalSfId) : true);
+                    if ((synthEngine || program !== undefined) && !progAlreadySet) {
+                        var sfHandle = finalSfId ? _sfHandleMap.get(finalSfId) : undefined;
+                        console.log('[SonicSF] selectProgram for channel:', ch, 'sfHandle:', sfHandle, 'bank:', finalBank, 'prog:', finalProg);
+                        if (sfHandle !== undefined) {
+                            try {
+                                // Percussion (bank 128): tìm preset HỢP LỆ trong
+                                // font — quét bank 128 + bank 0 (0-127) MỘT LẦN,
+                                // cache theo sfId. Trước đây chỉ thử 4 preset cố
+                                // định → font không có → cache channel = (128,0)
+                                // INVALID → note sau skip re-select (progAlreadySet)
+                                // → noteon preset rỗng = CÂM ("1 âm đầu rồi câm").
+                                if (finalBank === 128) {
+                                    var _vKey = finalSfId || ('h' + sfHandle);
+                                    if (_validPercCache[_vKey] === undefined) {
+                                        var _found = null;
+                                        for (var _b = 0; _b < 2 && !_found; _b++) {
+                                            var _bk = _b === 0 ? 128 : 0;
+                                            for (var _p = 0; _p < 128 && !_found; _p++) {
+                                                try {
+                                                    if (_fluidModule._fluid_synth_program_select(_synthPtr, 9, sfHandle, _bk, _p) === 0) {
+                                                        _found = [_bk, _p];
+                                                    }
+                                                } catch (e) {}
+                                            }
+                                        }
+                                        _validPercCache[_vKey] = _found;
+                                    }
+                                    if (_validPercCache[_vKey]) {
+                                        finalBank = _validPercCache[_vKey][0];
+                                        finalProg = _validPercCache[_vKey][1];
+                                    }
+                                }
+                                var _selRet = _fluidModule._fluid_synth_program_select(_synthPtr, ch, sfHandle, finalBank, finalProg);
+                            } catch (e) {}
+                        } else {
+                            try { _fluidModule._fluid_synth_bank_select(_synthPtr, ch, finalBank); } catch (e) {}
+                            try { _fluidModule._fluid_synth_program_change(_synthPtr, ch, finalProg); } catch (e) {}
+                        }
+                        if (!_channels[ch]) _channels[ch] = {};
+                        _channels[ch].bank = finalBank;
+                        _channels[ch].program = finalProg;
+                        _channels[ch].sfId = finalSfId;
+                    }
+                    console.log('[SonicSF] noteon channel:', ch, 'pitch:', midiPitch, 'vel:', midiVel, 'sfId:', finalSfId);
+                    _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) {}
+                        }, durationMs);
+                    }
+                } 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();
+            }
+        },
+
+        // Hủy mọi note-on được schedule (tương lai) + note-off mọi notes đang
+        // ngân — gọi khi STOP/PAUSE để hết "âm thanh bị stuck" (note-on chưa
+        // bắn vẫn bắn sau khi dừng; notes durationMs>=60000 không có note-off
+        // tự động → ngân vô hạn → VU master nhảy dù không play).
+        panic: function () {
+            _scheduledNotes.forEach(function (sn) { if (sn.on) { clearTimeout(sn.on); sn.on = null; } });
+            _scheduledNotes = [];
+            if (_initialized && _fluidModule) {
+                // noteoff TỪNG note đang ngân (binding _fluid_synth_noteoff chắc
+                // chắn tồn tại — đã dùng cho duration hết) — all_notes_off có
+                // thể không có trong WASM exports (catch nuốt → notes kẹt).
+                Object.keys(_activeNotes).forEach(function (key) {
+                    var parts = key.split(':');
+                    var pitch = parseInt(parts[1], 10);
+                    (_activeNotes[key] || []).forEach(function (ch) {
+                        try { _fluidModule._fluid_synth_noteoff(_synthPtr, ch, pitch); } catch (e) {}
+                    });
+                });
+                try {
+                    for (var c = 0; c < 16; c++) _fluidModule._fluid_synth_all_notes_off(_synthPtr, c);
+                } catch (e) {}
+            }
+            _activeNotes = {};
+        },
+
+        _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;
+            // CHỈ dùng cache channel khi KHÔNG có program/synthEngine được
+            // truyền — trước đây override program của track bằng cache channel
+            // (bị track khác cùng channel ghi đè → preview note vẽ mới mang
+            // nhạc cụ của track TRƯỚC).
+            if (program === undefined && 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' && isFinite(velocity) && !isNaN(velocity)) ? (velocity > 1 ? velocity / 127 : velocity) : 0.8;
+            if (isNaN(vel)) vel = 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) {
+                // noteoff từng note đang ngân (binding chắc chắn tồn tại) —
+                // phòng all_notes_off không có trong WASM exports.
+                Object.keys(_activeNotes).forEach(function (key) {
+                    var parts = key.split(':');
+                    var pitch = parseInt(parts[1], 10);
+                    (_activeNotes[key] || []).forEach(function (ch) {
+                        try { _fluidModule._fluid_synth_noteoff(_synthPtr, ch, pitch); } catch (e) {}
+                    });
+                });
+                for (var ch = 0; ch < 16; ch++) {
+                    try { _fluidModule._fluid_synth_all_notes_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]; });
+            _activeNotes = {};
         },
 
-        // 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 +788,69 @@
         }
     };
 
+    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 maxQueue = QUEUE_TARGET;
+        var queueDepth = 0;
+        var lastTick = performance.now();
+        var frameMs = (block / _audioCtx.sampleRate) * 1000;
+
+        // Track consumption by wall-clock time instead of async messages — immune
+        // to message-latency races that could underrun (silence gaps → crackle).
+        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));
+                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 now = performance.now();
+            queueDepth = Math.max(0, queueDepth - (now - lastTick) / frameMs);
+            lastTick = now;
+            var needed = Math.min(maxQueue - queueDepth, maxQueue);
+            for (var i = 0; i < needed; i++) {
+                pushFrame();
+            }
+        }
+
+        _renderTimer = setInterval(fillLoop, Math.max(4, frameMs * 0.5));
+    }
+
+    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/services/storage.js

@@ -21,7 +21,11 @@
                     solo: t.solo,
                     color: t.color,
                     markers: t.markers || [],
-                    serverFileId: t.serverFileId || null
+                    serverFileId: t.serverFileId || null,
+                    clips: t.clips || [],
+                    sections: t.sections || [],
+                    midiItems: t.midiItems || [],
+                    channelInfo: t.channelInfo || null
                 }))
             };
         }
@@ -56,11 +60,13 @@
     }
 
     let autoSaveTimer = null;
+    let lastGetProjectStateCallback = null;
     function scheduleTempAutoSave(getProjectStateCallback) {
+        if (getProjectStateCallback) lastGetProjectStateCallback = getProjectStateCallback;
         if (autoSaveTimer) clearTimeout(autoSaveTimer);
         autoSaveTimer = setTimeout(async () => {
             try {
-                const state = getProjectStateCallback();
+                const state = lastGetProjectStateCallback ? lastGetProjectStateCallback() : null;
                 if (!state || (!state.tracks && !state.main_session)) return;
                 const dataJson = JSON.stringify(state);
                 localStorage.setItem('sonic_temp_project', dataJson);
@@ -72,10 +78,26 @@
             }
         }, 2000);
     }
+    // Lưu NGAY (bỏ debounce 2s) — dùng cho thay đổi cần bền vững tức thì (đổi màu track)
+    async function flushTempAutoSave() {
+        if (autoSaveTimer) { clearTimeout(autoSaveTimer); autoSaveTimer = null; }
+        try {
+            const state = lastGetProjectStateCallback ? lastGetProjectStateCallback() : null;
+            if (!state || (!state.tracks && !state.main_session)) return;
+            const dataJson = JSON.stringify(state);
+            localStorage.setItem('sonic_temp_project', dataJson);
+            if (window.SonicAPI && localStorage.getItem('sonic_token')) {
+                await window.SonicAPI.saveTempProject(dataJson).catch(() => {});
+            }
+        } catch (e) {
+            console.warn("Flush temp project warning:", e);
+        }
+    }
 
     window.SonicStorage = {
         exportProjectToSFS,
         importProjectFromSFSFile,
-        scheduleTempAutoSave
+        scheduleTempAutoSave,
+        flushTempAutoSave
     };
 })();

app/static/js/services/undoRedoEngine.js

@@ -0,0 +1,74 @@
+// SonicForge Studio - Unified Undo/Redo Engine
+// Handles all undoable actions across MAIN SESSION and SECTION-TAB
+
+const UndoRedoEngine = (function() {
+  const MAX_HISTORY = 50;
+  const history = [];
+  let historyIndex = -1;
+
+  function push(entry) {
+    history.push(entry);
+    if (history.length > MAX_HISTORY) {
+      history.shift();
+    }
+    historyIndex = history.length - 1;
+  }
+
+  function undo() {
+    if (historyIndex < 0) return null;
+    const entry = history[historyIndex];
+    historyIndex--;
+    return entry;
+  }
+
+  function redo() {
+    if (historyIndex >= history.length - 1) return null;
+    historyIndex++;
+    const entry = history[historyIndex];
+    return entry;
+  }
+
+  function canUndo() { return historyIndex >= 0; }
+  function canRedo() { return historyIndex < history.length - 1; }
+
+  function clear() {
+    history.length = 0;
+    historyIndex = -1;
+  }
+
+  function execute(entry) {
+    // entry: { type, scope, label, before, after, undo, redo }
+    // Trim future history if we're not at the end
+    if (historyIndex < history.length - 1) {
+      history.splice(historyIndex + 1);
+    }
+    push(entry);
+    return entry;
+  }
+
+  function getStatus() {
+    return {
+      canUndo: canUndo(),
+      canRedo: canRedo(),
+      undoCount: historyIndex + 1,
+      redoCount: history.length - historyIndex - 1,
+      lastAction: history[historyIndex]?.type || null,
+      lastLabel: history[historyIndex]?.label || null
+    };
+  }
+
+  return {
+    push,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    clear,
+    execute,
+    getStatus,
+    history,
+    historyIndex
+  };
+})();
+
+window.UndoRedoEngine = UndoRedoEngine;

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

@@ -0,0 +1,44 @@
+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 || out.length === 0) return true;
+    this.called++;
+    const numCh = out.length;
+    const len = out[0].length;
+    const qL = this.leftQ;
+    const qR = this.rightQ;
+    let fi = 0;
+    let si = 0;
+    // Handle any output channel count (mono devices produce 1 channel, so
+    // out[1] may be undefined — never write into a missing channel).
+    for (let i = 0; i < len; i++) {
+      if (fi >= qL.length) {
+        for (let c = 0; c < numCh; c++) out[c][i] = 0;
+        continue;
+      }
+      for (let c = 0; c < numCh; c++) {
+        out[c][i] = c % 2 === 0 ? qL[fi][si] : 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); }
+    return true;
+  }
+}
+
+registerProcessor('fluidsynth-bridge', FluidSynthBridge);

app/storage/.secret_key

@@ -0,0 +1 @@
+8d26e2b55e73579d1bb3c37b4878f1845ef9cbf50a8e4ee6f7deaa2ab80db32d

app/templates/index.html

@@ -8,16 +8,24 @@
     <link rel="icon" type="image/svg+xml" href="/favicon.svg">
     <script src="https://cdn.tailwindcss.com"></script>
     <script src="https://unpkg.com/lucide@latest"></script>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css" crossorigin="anonymous" referrerpolicy="no-referrer">
     <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=202608038200"></script>
+    <script src="/static/js/services/soundfontStorage.js?v=202607271016"></script>
+    <script src="/static/js/services/soundfontPlayer.js?v=202608070635"></script>
+    <script src="/static/js/services/aiGateway.js?v=202608037200"></script>
+    <script src="/static/js/services/dawCommandDispatcher.js?v=202607271016"></script>
+    <script src="/static/js/services/pianoRollTabService.js?v=202607272044"></script>
+    <script src="/static/js/services/ghostNoteExtractor.js?v=202607271727"></script>
+    <script src="/static/js/services/midiExtractor.js?v=202607281052"></script>
+    <script src="/static/js/services/promptTemplateManager.js?v=202607281039"></script>
+    <script src="/static/js/services/undoRedoEngine.js?v=202607290941"></script>
+    <script src="/static/js/app.precompiled.js?v=202608070950" defer></script>
+    <link rel="stylesheet" href="/static/css/styles.css?v=202607271016">
     <style>
         :root {
             --right-sidebar-width: 320px;
@@ -235,6 +243,170 @@
         svg, i[data-lucide] {
             pointer-events: none;
         }
+
+        /* Ozone Mastering Module Styles */
+        .oz-panel {
+            background: linear-gradient(180deg, #131822 0%, #0d1118 100%);
+            border: 1px solid rgba(255, 255, 255, 0.07);
+        }
+        .oz-card {
+            background: #18202c;
+            border: 1px solid rgba(255, 255, 255, 0.1);
+            transition: all 0.15s ease;
+        }
+        .oz-card-active {
+            background: #1e2a3a;
+            border-color: #38bdf8;
+            box-shadow: 0 0 12px rgba(56, 189, 248, 0.2);
+        }
+        .knob-container { touch-action: none; user-select: none; }
+        .knob-dial {
+            transition: transform 0.05s ease-out;
+            box-shadow: inset 0 1px 3px rgba(255,255,255,0.15), 0 3px 8px rgba(0,0,0,0.8);
+        }
+        .oz-scrollbar::-webkit-scrollbar { width: 4px; height: 4px; }
+        .oz-scrollbar::-webkit-scrollbar-track { background: #080b12; }
+        .oz-scrollbar::-webkit-scrollbar-thumb { background: #1e293b; border-radius: 2px; }
+        .oz-scrollbar::-webkit-scrollbar-thumb:hover { background: #334155; }
+        .oz-font-mono { font-family: 'JetBrains Mono', monospace; }
+
+        /* Master & Track Strip Console Styles (from md/47, md/48) */
+        .strip-bg {
+            background: linear-gradient(180deg, #2f2f2f 0%, #222222 100%);
+            border: 1px solid #141414;
+            box-shadow: inset 1px 1px 0 rgba(255,255,255,0.08), 0 8px 24px rgba(0,0,0,0.8);
+        }
+        .strip-bg-track {
+            background: linear-gradient(180deg, #2c2c2c 0%, #1e1e1e 100%);
+            border: 1px solid #111111;
+            box-shadow: inset 1px 1px 0 rgba(255,255,255,0.08), 0 10px 30px rgba(0,0,0,0.85);
+        }
+
+        .fader-track {
+            background: #121212;
+            box-shadow: inset 1px 1px 3px rgba(0,0,0,0.9), 1px 1px 0 rgba(255,255,255,0.05);
+        }
+        .fader-track-bg {
+            background: #101010;
+            box-shadow: inset 1px 1px 3px rgba(0,0,0,0.9), 1px 1px 0 rgba(255,255,255,0.05);
+        }
+
+        /* DAW Metallic Button */
+        .btn-daw {
+            background: linear-gradient(180deg, #444 0%, #2a2a2a 100%);
+            border: 1px solid #1a1a1a;
+            box-shadow: inset 0 1px 0 rgba(255,255,255,0.15), 0 2px 4px rgba(0,0,0,0.5);
+            transition: all 0.1s ease;
+        }
+        .btn-daw:hover {
+            background: linear-gradient(180deg, #555 0%, #333 100%);
+        }
+        .btn-daw:active {
+            box-shadow: inset 0 2px 4px rgba(0,0,0,0.8);
+            transform: translateY(0.5px);
+        }
+
+        /* Teal Active State (FX & Power Button) */
+        .btn-teal-active {
+            background: linear-gradient(180deg, #10b981 0%, #047857 100%) !important;
+            border-color: #34d399 !important;
+            color: #ffffff !important;
+            box-shadow: 0 0 10px rgba(16, 185, 129, 0.6) !important;
+        }
+
+        /* Mute Active State */
+        .btn-mute-active {
+            background: linear-gradient(180deg, #ef4444 0%, #991b1b 100%) !important;
+            border-color: #f87171 !important;
+            color: #ffffff !important;
+            box-shadow: 0 0 8px rgba(239, 68, 68, 0.6) !important;
+        }
+
+        /* Solo Active State */
+        .btn-solo-active {
+            background: linear-gradient(180deg, #eab308 0%, #854d0e 100%) !important;
+            border-color: #fde047 !important;
+            color: #000000 !important;
+            box-shadow: 0 0 8px rgba(234, 179, 8, 0.6) !important;
+        }
+
+        /* Mono Active State */
+        .btn-mono-active {
+            background: linear-gradient(180deg, #3b82f6 0%, #1e40af 100%) !important;
+            border-color: #60a5fa !important;
+            color: #ffffff !important;
+        }
+
+        /* Record Arm Active State */
+        .btn-arm-active {
+            background: radial-gradient(circle, #ef4444 0%, #7f1d1d 100%) !important;
+            border-color: #fca5a5 !important;
+            box-shadow: 0 0 12px rgba(239, 68, 68, 0.9), inset 0 1px 2px rgba(255,255,255,0.8) !important;
+            animation: pulse-red 1.2s infinite alternate;
+        }
+
+        @keyframes pulse-red {
+            0% { box-shadow: 0 0 6px rgba(239, 68, 68, 0.6); }
+            100% { box-shadow: 0 0 16px rgba(239, 68, 68, 1); }
+        }
+
+        /* Custom Vertical Range Fader Slider */
+        input[type=range].fader-slider {
+            -webkit-appearance: none;
+            appearance: none;
+            writing-mode: vertical-lr;
+            direction: rtl;
+            background: transparent;
+            cursor: pointer;
+            margin: 0;
+            padding: 0;
+            flex: 1;
+            min-height: 20px;
+            width: 100%;
+        }
+        input[type=range].fader-slider::-webkit-slider-thumb {
+            -webkit-appearance: none;
+            height: 24px;
+            width: 22px;
+            background: linear-gradient(180deg, #e2e8f0 0%, #64748b 45%, #1e293b 50%, #94a3b8 100%);
+            border: 1px solid #000000;
+            border-radius: 2px;
+            box-shadow: 0 4px 8px rgba(0,0,0,0.9), inset 0 1px 1px rgba(255,255,255,0.9);
+        }
+        input[type=range].fader-slider::-moz-range-thumb {
+            height: 24px;
+            width: 22px;
+            background: linear-gradient(180deg, #e2e8f0 0%, #64748b 45%, #1e293b 50%, #94a3b8 100%);
+            border: 1px solid #000000;
+            border-radius: 2px;
+            box-shadow: 0 4px 8px rgba(0,0,0,0.9), inset 0 1px 1px rgba(255,255,255,0.9);
+        }
+
+        /* Media Explorer: horizontal volume slider + selected file row */
+        input[type=range].me-fader-slider {
+            -webkit-appearance: none;
+            appearance: none;
+            background: #111;
+            height: 6px;
+            border-radius: 3px;
+            border: 1px solid #555;
+            cursor: pointer;
+        }
+        input[type=range].me-fader-slider::-webkit-slider-thumb {
+            -webkit-appearance: none;
+            height: 16px;
+            width: 12px;
+            background: linear-gradient(180deg, #e2e8f0 0%, #64748b 50%, #1e293b 100%);
+            border: 1px solid #000;
+            border-radius: 2px;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.5);
+            cursor: pointer;
+        }
+        .file-row-selected {
+            background-color: #3399ff !important;
+            color: #ffffff !important;
+        }
+        .file-row-selected .file-icon { color: #ffffff !important; }
     </style>
 </head>
 

app/test_sf3_load.py

@@ -0,0 +1,20 @@
+import os
+import sys
+
+sys.path.insert(0, "/app")
+
+try:
+    import fluidsynth
+    print("fluidsynth import successful.")
+    
+    fl = fluidsynth.Synth()
+    # Try to load a pre-existing system SF3
+    sf3_path = "/opt/daw_engine/soundfonts/Equinox_Grand_Pianos.sf3"
+    print(f"Checking if {sf3_path} exists: {os.path.exists(sf3_path)}")
+    if os.path.exists(sf3_path):
+        h = fl.sfload(sf3_path)
+        print(f"Loaded {sf3_path}, handle: {h}")
+    else:
+        print("Equinox_Grand_Pianos.sf3 not found.")
+except Exception as e:
+    print(f"Failed: {e}")

app/test_sf_convert.py

@@ -0,0 +1,66 @@
+import os
+import sys
+import logging
+
+# Ensure app is in path
+sys.path.insert(0, "/app")
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("test_sf_convert")
+
+from app.core.soundfont_converter import SoundFontConverter
+
+def test():
+    sf2_dir = "/app/app/storage/soundfonts"
+    sf2_files = [os.path.join(sf2_dir, f) for f in os.listdir(sf2_dir) if f.endswith(".sf2") and "_decomp" not in f]
+    if not sf2_files:
+        logger.error("No SF2 files found in /app/app/storage/soundfonts")
+        return
+
+    sf2_path = sf2_files[0]
+    logger.info(f"Testing with SF2 file: {sf2_path}")
+
+    converter = SoundFontConverter()
+    
+    # Check ffmpeg encoder support
+    has_ogg = converter._check_ffmpeg_ogg()
+    logger.info(f"ffmpeg with libvorbis available: {has_ogg}")
+
+    # Convert SF2 -> SF3
+    sf3_path = sf2_path.replace(".sf2", ".sf3")
+    if os.path.exists(sf3_path):
+        os.remove(sf3_path)
+
+    logger.info("Converting SF2 -> SF3...")
+    result_path = converter.convert_sf2_to_sf3(sf2_path)
+    logger.info(f"Result path from convert_sf2_to_sf3: {result_path}")
+    
+    if result_path.endswith(".sf3"):
+        logger.info(f"SF3 file exists: {os.path.exists(sf3_path)}")
+        if os.path.exists(sf3_path):
+            logger.info(f"SF3 size: {os.path.getsize(sf3_path)} bytes")
+            # Verify if it plays audio
+            plays = converter._sf3_plays_audio(sf3_path)
+            logger.info(f"SF3 plays audio (pyfluidsynth verify): {plays}")
+            
+            # Now test decompression back to SF2
+            decomp_sf2 = sf3_path.replace(".sf3", "_decomp.sf2")
+            if os.path.exists(decomp_sf2):
+                os.remove(decomp_sf2)
+            
+            logger.info("Decompressing SF3 -> SF2...")
+            try:
+                decomp_result = converter.sf3_to_sf2(sf3_path, decomp_sf2)
+                logger.info(f"Decompress result path: {decomp_result}")
+                if os.path.exists(decomp_sf2):
+                    logger.info(f"Decompressed SF2 size: {os.path.getsize(decomp_sf2)} bytes")
+                    # Check if it plays
+                    decomp_plays = converter._sf3_plays_audio(decomp_sf2)
+                    logger.info(f"Decompressed SF2 plays audio: {decomp_plays}")
+            except Exception as e:
+                logger.error(f"Decompression failed: {e}", exc_info=True)
+    else:
+        logger.warning("Conversion did not produce an SF3 path.")
+
+if __name__ == "__main__":
+    test()

build.mjs

@@ -0,0 +1,14 @@
+// Rebuild app.precompiled.js from app.jsx using @babel/standalone (avoids the
+// Babel 8 ESM-only CLI conflict). Mirrors package.json's build script:
+//   babel app/static/js/app.jsx --config-file ./babel.config.json -o app/static/js/app.precompiled.js
+import * as Babel from '@babel/standalone';
+import { readFileSync, writeFileSync } from 'fs';
+
+const src = readFileSync('app/static/js/app.jsx', 'utf8');
+const out = Babel.transform(src, {
+  presets: ['react'],
+  filename: 'app.jsx',
+  sourceType: 'script',
+}).code;
+writeFileSync('app/static/js/app.precompiled.js', out);
+console.log('BUILD OK', out.length, 'bytes');

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}$.

md/40_MIDI_GHOSTNOTE.md

@@ -0,0 +1,259 @@
+# TECHNICAL SPECIFICATION: GHOST NOTES FEATURE IN PIANO ROLL TAB
+
+This document details the workflow and processing algorithms for opening any `MIDIItem` (for example, MIDI Item 1 spanning Bar 0 to Bar 4) on the main Timeline in a Piano Roll Tab, while extracting and displaying all notes from other tracks occupying the same time interval (Bar 0 - Bar 4) as Ghost Notes (faded reference notes that cannot be interactively edited).
+
+---
+
+## 1. DATA FLOW & MODULE ARCHITECTURE DIAGRAM
+
+```text
+[ USER DBL-CLICK ITEM 1 ] 
+(Track A, Bar 0 - 4)
+           |
+           v
+[ 1. Context Extractor Engine ]
+   ├── Target Item: Active Editing Item
+   ├── Window Bounds: [Bar 0.0 -> Bar 4.0]
+   └── Scan All Other Tracks (B, C, D...)
+           |
+           v
+[ 2. Overlap Filtering Algorithm ]
+   ├── Track B (Bass): Item B1 (Bar 0 - 8)  -> Overlap! Slice [Bar 0 -> 4]
+   ├── Track C (Pads): Item C1 (Bar 2 - 6)  -> Overlap! Slice [Bar 2 -> 4]
+   └── Track D (Lead): Item D1 (Bar 5 - 8)  -> Out of bounds! Ignore
+           |
+           v
+[ 3. Piano Roll State Store ]
+   ├── activeItem: MIDI Item 1 (Full Edit Access)
+   └── ghostLayers: [ Track B Notes, Track C Notes ] (Read-Only)
+           |
+           v
+[ 4. Multi-Layer Canvas Renderer ]
+   ├── Layer 1: Background Grid & Pitch Keys
+   ├── Layer 2: Ghost Notes (Opacity 25%, Muted Color, Pointer Events OFF)
+   └── Layer 3: Active Notes (Full Opacity, Drag/Drop/Resize Allowed)
+
+```
+
+---
+
+## 2. TIME-WINDOW OVERLAP FILTERING ALGORITHM
+
+To determine whether a `MIDIItem` on another track overlaps with the interval $[start\_bar, end\_bar]$ of MIDI Item 1, a 1D geometric condition is applied:
+
+### Overlap Condition
+
+Two time intervals $[A_{start}, A_{end}]$ and $[B_{start}, B_{end}]$ intersect if and only if:
+
+$$B_{start} < A_{end} \quad \text{AND} \quad B_{end} > A_{start}$$
+
+Where:
+
+* $A_{start} = \text{Item1.start\_bar} = 0.0$
+* $A_{end} = \text{Item1.start\_bar} + \text{Item1.duration\_bars} = 4.0$
+
+```javascript
+// app/static/js/services/ghostNoteExtractor.js
+
+/**
+ * Extracts a list of Ghost Notes from other tracks within the specified Bar window
+ * @param {Object} sessionState - Full Main Session state object
+ * @param {string} targetTrackId - ID of the currently active editing Track (Track A)
+ * @param {number} windowStartBar - Start bar position of the active Item (e.g., 0.0)
+ * @param {number} windowDurationBars - Bar duration of the active Item (e.g., 4.0)
+ * @returns {Array} List of normalized Ghost Layers
+ */
+export function extractGhostLayers(sessionState, targetTrackId, windowStartBar, windowDurationBars) {
+  const windowEndBar = windowStartBar + windowDurationBars;
+  const timeSigNumerator = sessionState.metadata.time_signature_numerator || 4;
+  
+  const ghostLayers = [];
+
+  // Iterate over all tracks in Main Session
+  sessionState.main_session.tracks.forEach((track) => {
+    // Ignore active editing track and non-MIDI or muted tracks
+    if (track.id === targetTrackId || track.type !== "MIDI" || track.mute) {
+      return;
+    }
+
+    const trackGhostNotes = [];
+
+    // Iterate over all items in target candidate tracks
+    track.items.forEach((item) => {
+      if (item.type !== "MIDI_ITEM") return;
+
+      const itemStartBar = item.start_bar;
+      const itemEndBar = item.start_bar + item.duration_bars;
+
+      // Evaluate Overlap Condition
+      if (itemStartBar < windowEndBar && itemEndBar > windowStartBar) {
+        const itemOffsetBar = item.clip_start_offset_bars || 0.0;
+
+        item.source_data.notes.forEach((note) => {
+          // Convert internal note start_beat to absolute timeline beats
+          const noteAbsoluteBeat = (itemStartBar * timeSigNumerator) + note.start_beat - (itemOffsetBar * timeSigNumerator);
+          const noteEndAbsoluteBeat = noteAbsoluteBeat + note.duration_beats;
+
+          const windowStartBeat = windowStartBar * timeSigNumerator;
+          const windowEndBeat = windowEndBar * timeSigNumerator;
+
+          // Retain notes truly within the visible bounds [windowStartBeat -> windowEndBeat]
+          if (noteAbsoluteBeat < windowEndBeat && noteEndAbsoluteBeat > windowStartBeat) {
+            trackGhostNotes.push({
+              id: `ghost_${note.id}`,
+              pitch: note.pitch,
+              // Convert beat position to relative coordinates of the Piano Roll Window (0 -> duration_beats)
+              relative_start_beat: noteAbsoluteBeat - windowStartBeat,
+              duration_beats: note.duration_beats,
+              velocity: note.velocity,
+              original_track_name: track.name,
+              original_track_color: track.color || "#888888"
+            });
+          }
+        });
+      }
+    });
+
+    if (trackGhostNotes.length > 0) {
+      ghostLayers.push({
+        track_id: track.id,
+        track_name: track.name,
+        track_color: track.color || "#6b7280",
+        notes: trackGhostNotes
+      });
+    }
+  });
+
+  return ghostLayers;
+}
+
+```
+
+---
+
+## 3. STATE STRUCTURE FOR PIANO ROLL TAB
+
+When the user opens MIDI Item 1, the Tab Controller generates an isolated context payload for the Piano Roll:
+
+```javascript
+// Data Payload passed into the PianoRollTab Component
+const pianoRollTabContext = {
+  tab_id: "tab_pianoroll_item_1",
+  title: "Piano Roll - MIDI Item 1",
+  type: "PIANO_ROLL_TAB",
+  parent_tab_id: "tab_main_session",
+  
+  // 1. Target Item open for direct interactive editing
+  active_context: {
+    track_id: "track_A",
+    item_id: "item_1",
+    item_name: "MIDI Item 1",
+    start_bar: 0.0,
+    duration_bars: 4.0,
+    notes: [/* Original source MIDI notes of Item 1 */]
+  },
+
+  // 2. Read-only Ghost Layers displayed as background reference indicators
+  ghost_layers: [
+    {
+      track_id: "track_B_bass",
+      track_name: "Track B (Bass)",
+      track_color: "#3b82f6", // Green / Blue
+      notes: [
+        { pitch: 36, relative_start_beat: 0.0, duration_beats: 4.0, velocity: 0.9 },
+        { relative_start_beat: 4.0, pitch: 38, duration_beats: 4.0, velocity: 0.8 }
+      ]
+    },
+    {
+      track_id: "track_C_pads",
+      track_name: "Track C (Pads)",
+      track_color: "#ec4899", // Pink
+      notes: [
+        { pitch: 60, relative_start_beat: 8.0, duration_beats: 8.0, velocity: 0.6 }
+      ]
+    }
+  ]
+};
+
+```
+
+---
+
+## 4. MULTI-LAYER CANVAS RENDERER WORKFLOW
+
+Inside the Piano Roll canvas rendering module, elements are drawn sequentially by z-index order to position Ghost Notes behind Active Notes:
+
+```javascript
+// app/static/js/views/pianoRollRenderer.js
+
+export function renderPianoRollCanvas(ctx, canvasWidth, canvasHeight, viewState, activeItem, ghostLayers) {
+  const { zoomX, zoomY, scrollX, scrollY, noteHeight } = viewState;
+
+  // -----------------------------------------------------------------
+  // LAYER 1: BACKGROUND & GRID LINES
+  // -----------------------------------------------------------------
+  drawPianoGrid(ctx, canvasWidth, canvasHeight, viewState);
+
+  // -----------------------------------------------------------------
+  // LAYER 2: GHOST NOTES (BACKGROUND REFERENCE FROM OTHER TRACKS)
+  // -----------------------------------------------------------------
+  if (ghostLayers && ghostLayers.length > 0) {
+    ghostLayers.forEach((layer) => {
+      ctx.save();
+      // Set faded opacity (20% - 30% opacity)
+      ctx.globalAlpha = 0.25;
+      ctx.fillStyle = layer.track_color;
+      ctx.strokeStyle = layer.track_color;
+
+      layer.notes.forEach((note) => {
+        const x = (note.relative_start_beat - scrollX) * zoomX;
+        const y = (127 - note.pitch - scrollY) * noteHeight;
+        const w = note.duration_beats * zoomX;
+        const h = noteHeight - 1; // 1px border gap
+
+        // Draw Ghost note body (Dashed border or light stroke)
+        ctx.fillRect(x, y, w, h);
+        ctx.setLineDash([2, 2]); // Dashed lines indicating non-interactive status
+        ctx.lineWidth = 1;
+        ctx.strokeRect(x, y, w, h);
+      });
+
+      ctx.restore();
+    });
+  }
+
+  // -----------------------------------------------------------------
+  // LAYER 3: ACTIVE NOTES (EDITABLE NOTES FOR ITEM 1)
+  // -----------------------------------------------------------------
+  activeItem.notes.forEach((note) => {
+    ctx.save();
+    ctx.globalAlpha = 1.0; // 100% full opacity
+    
+    const x = (note.start_beat - scrollX) * zoomX;
+    const y = (127 - note.pitch - scrollY) * noteHeight;
+    const w = note.duration_beats * zoomX;
+    const h = noteHeight - 1;
+
+    // Bright fill colors for active notes
+    ctx.fillStyle = note.selected ? "#f59e0b" : "#10b981"; // Orange if selected, green if default
+    ctx.fillRect(x, y, w, h);
+
+    ctx.strokeStyle = "#ffffff";
+    ctx.lineWidth = 1;
+    ctx.strokeRect(x, y, w, h);
+
+    ctx.restore();
+  });
+}
+
+```
+
+---
+
+## 5. POINTER INTERACTION RULES
+
+To prevent accidental modification or drag interactions with Ghost Notes:
+
+* **Hit-Testing Isolation:** On pointer events (`mousedown`, `mousemove`, or marquee selection), the Hit-Test algorithm queries `activeItem.notes` exclusively. `ghostLayers` items are omitted from event evaluation.
+* **Toggle Ghost Notes Visibility:** The Piano Roll toolbar includes an Eye / Ghost icon button (`[👻 Ghost Notes]`) allowing operators to toggle the visibility of the reference background layer.
+* **Live Synchronous Updates:** Modifying a note on Track B within the Main Session or an adjacent tab dispatches an `EVENT_SESSION_UPDATED` Event Bus signal. The active Piano Roll Tab receives this event and invokes `extractGhostLayers()` to dynamically redraw updated Ghost Note positions.

md/41_INSTRUMENT.md

@@ -0,0 +1,230 @@
+# TECHNICAL SPECIFICATION: INSTRUMENT MANAGEMENT & DATA ISOLATION FOR MULTI-ITEM PIANO ROLL TABS
+
+This document specifies the data architecture, state flow, and audio channel routing rules required to ensure that when a single Piano Roll Tab opens multiple `MIDIItems` simultaneously from different Tracks, modifying the instrument/synth engine for the active item applies exclusively to its parent track without affecting any other items or tracks.
+
+---
+
+## 1. DATA OWNERSHIP HIERARCHY
+
+To prevent cross-track instrument configuration leakage, the system enforces **Track-Level Ownership**:
+
+* **Track (`TrackState`):** The sole owner of synth engine configurations (`synth_engine`), assigned MIDI channel (`midi_channel`), and mixing parameters (`volume_db`, `pan`).
+* **MIDI Item (`MIDIItemState`):** Contains **no** independent synth configuration parameters. An item holds only its array of notes (`source_data.notes`) and a mandatory parent reference pointer (`parent_track_id`).
+
+```text
+[ Main Session / Project State ]
+       │
+       ├── Track 1 (id: "track_01", midi_channel: 0, synth_engine: "DSK_Pipa")
+       │     └── Item 1 (id: "item_01", parent_track_id: "track_01") ──┐
+       │                                                              │
+       └── Track 2 (id: "track_02", midi_channel: 1, synth_engine: "None")│
+             └── Item 2 (id: "item_02", parent_track_id: "track_02") ──┼─► [ Piano Roll Tab Context ]
+                                                                      │   (Active Item Selector Dropdown)
+                                                                      │   ├── Selected: Item 1 -> Scope: Track 1
+                                                                      └── └── Inactive: Item 2 -> Scope: Track 2
+
+```
+
+---
+
+## 2. MULTI-ITEM PIANO ROLL TAB STATE STRUCTURE
+
+When a user opens one or more `MIDIItems` inside the same Piano Roll Tab, the Tab Context State maintains a list of open item IDs along with an `active_item_id` representing the item currently selected in the toolbar dropdown:
+
+```javascript
+// Tab Context state structure for a Piano Roll Tab editing multiple items
+const multiItemPianoRollTabContext = {
+  tab_id: "tab_pianoroll_multi_editor",
+  title: "Piano Roll Editor",
+  type: "PIANO_ROLL_TAB",
+  
+  // 1. Array of all MIDI Item IDs currently loaded in this Tab
+  open_item_ids: ["item_01", "item_02"],
+  
+  // 2. ID of the item currently selected for direct editing via the Toolbar Dropdown
+  active_item_id: "item_01",
+  
+  // 3. Dynamic Computed Context (Derived State based on active_item_id)
+  active_scope: {
+    item_id: "item_01",
+    parent_track_id: "track_01",     // Reverse pointer to Track 1
+    midi_channel: 0,                 // Dedicated MIDI Channel for Track 1
+    current_synth_engine: {
+      type: "soundfont",
+      plugin_id: "dsk_asian_dreamz",
+      soundfont_bank: 0,
+      soundfont_program: 0           // Pipa
+    }
+  }
+};
+
+```
+
+---
+
+## 3. ISOLATED INSTRUMENT SELECTION WORKFLOW
+
+### Step 1: User switches `active_item_id` in the Toolbar Dropdown
+
+When the user selects `MIDI Item 2` from the Piano Roll Tab dropdown:
+
+1. The Tab Controller receives a `SWITCH_PIANO_ROLL_ACTIVE_ITEM` event.
+2. The system queries `MIDI Item 2` for its `parent_track_id` (e.g., returning `"track_02"`).
+3. The controller reads the current `synth_engine` configuration directly from `Track 2`.
+4. The Piano Roll Tab's Synth button label updates to reflect `Track 2`'s instrument (or displays `🎵 None (Default Synth)` if unassigned).
+
+### Step 2: User changes the instrument in the Piano Roll Synth Menu
+
+When the user opens the Synth menu on the Piano Roll toolbar and selects a new instrument (e.g., selecting `Vital VST3` or `Saxophone SoundFont`):
+
+1. The UI resolves the current `active_item_id` (`"item_01"`).
+2. The UI queries the parent track ID: `targetTrackId = getItemParentTrackId(active_item_id)`.
+3. The system dispatches an isolated mutation action:
+```javascript
+dispatch({
+  type: "UPDATE_TRACK_SYNTH_ENGINE",
+  payload: {
+    track_id: targetTrackId, // Modifies ONLY "track_01"; "track_02" remains untouched
+    synth_engine: {
+      type: "vst3",
+      plugin_id: "Vital",
+      soundfont_bank: 0,
+      soundfont_program: 0
+    }
+  }
+});
+
+```
+
+
+
+---
+
+## 4. AUDIO CHANNEL ISOLATION
+
+To ensure that triggering notes on `Item 1` plays the Pipa sound while `Item 2` plays the Vital patch without audio cross-talk, dedicated MIDI channels are assigned per track:
+
+### MIDI Channel Binding Rules
+
+| Track | MIDI Item | Parent Track ID | Dedicated MIDI Channel | Applied Instrument |
+| --- | --- | --- | --- | --- |
+| **Track 1** | MIDI Item 1 | `track_01` | Channel 0 | DSK_Asian_DreamZ (Pipa) |
+| **Track 2** | MIDI Item 2 | `track_02` | Channel 1 | Vital.vst3 |
+
+* **When configuring Instrument for Track 1:**
+The Client SoundEngine/Wasm routes configuration changes exclusively to Channel 0:
+```javascript
+soundFontPlayerInstance.selectInstrument(channel = 0, bank = 0, program = 0);
+
+```
+
+
+* **When configuring Instrument for Track 2:**
+The Client SoundEngine/Wasm routes configuration changes exclusively to Channel 1:
+```javascript
+soundFontPlayerInstance.selectInstrument(channel = 1, bank = 0, program = 56);
+
+```
+
+
+* **When previewing notes in the Piano Roll:**
+* If `MIDI Item 1` is active $\rightarrow$ Dispatch `noteOn(channel = 0, pitch, velocity)`.
+* If `MIDI Item 2` is active $\rightarrow$ Dispatch `noteOn(channel = 1, pitch, velocity)`.
+
+
+
+---
+
+## 5. CORE SERVICE IMPLEMENTATION (`pianoRollTabService.js`)
+
+```javascript
+// app/static/js/services/pianoRollTabService.js
+
+/**
+ * State Manager and Dispatcher for Multi-Item Piano Roll Tabs
+ */
+export class PianoRollTabManager {
+  constructor(sessionState, soundEngine) {
+    this.sessionState = sessionState;
+    this.soundEngine = soundEngine;
+  }
+
+  /**
+   * Retrieves parent Track by Item ID
+   */
+  getParentTrackByItemId(itemId) {
+    for (const track of this.sessionState.main_session.tracks) {
+      const item = track.items.find(i => i.id === itemId);
+      if (item) return track;
+    }
+    return null;
+  }
+
+  /**
+   * Updates instrument configuration from the Piano Roll Tab Toolbar
+   * @param {string} activeItemId - Currently selected Item ID in dropdown
+   * @param {Object} newSynthConfig - New Synth configuration object
+   */
+  setInstrumentFromPianoRoll(activeItemId, newSynthConfig) {
+    const parentTrack = this.getParentTrackByItemId(activeItemId);
+    
+    if (!parentTrack) {
+      console.error(`[PianoRoll] Parent Track not found for Item ID: ${activeItemId}`);
+      return;
+    }
+
+    console.log(`[PianoRoll] Applying new instrument to Track "${parentTrack.name}" (ID: ${parentTrack.id})`);
+
+    // 1. Update state exclusively on the parent Track
+    parentTrack.synth_engine = { ...newSynthConfig };
+
+    // 2. Resolve parent Track's dedicated MIDI Channel
+    const trackIndex = this.sessionState.main_session.tracks.findIndex(t => t.id === parentTrack.id);
+    const dedicatedMidiChannel = trackIndex % 16; // Assign channels 0-15
+
+    // 3. Dispatch instrument change to the Client Sound Engine ONLY FOR THIS CHANNEL
+    if (this.soundEngine) {
+      this.soundEngine.selectInstrument(
+        dedicatedMidiChannel,
+        newSynthConfig.soundfont_bank || 0,
+        newSynthConfig.soundfont_program || 0
+      );
+    }
+
+    // 4. Dispatch UI re-render event
+    window.dispatchEvent(new CustomEvent('DAW_STATE_UPDATED', { detail: this.sessionState }));
+  }
+
+  /**
+   * Switches the active item in the toolbar dropdown
+   */
+  switchActiveItem(tabContext, newActiveItemId) {
+    tabContext.active_item_id = newActiveItemId;
+    
+    const parentTrack = this.getParentTrackByItemId(newActiveItemId);
+    if (parentTrack) {
+      tabContext.active_scope = {
+        item_id: newActiveItemId,
+        parent_track_id: parentTrack.id,
+        current_synth_engine: parentTrack.synth_engine || { type: "none" }
+      };
+    }
+    
+    return tabContext;
+  }
+}
+
+```
+
+---
+
+## 6. UI/UX SAFETY CHECKS & ERROR PREVENTION
+
+* **Explicit Parent Track Indicators on Toolbar:**
+Next to the MIDI Item dropdown, the Piano Roll toolbar explicitly displays context labels:
+`[ Item Selector: MIDI Item 1 ▾ ] ── (Belongs to: Track 1)`
+The Synth Selector button displays: `[ 🎵 Synth (Track 1): DSK_Pipa ▾ ]`.
+* **Isolated Event Bus Mutators:**
+When invoking `setTrackInstrument`, global setters such as `setAllTracksInstrument()` or `global_synth_engine` mutations are strictly forbidden. Every state mutation function requires an explicit `track_id` parameter.
+* **Multi-Item Ghost Notes Rendering:**
+The item selected in the dropdown (`active_item_id`) is the sole editable item. All other items listed in `open_item_ids` render automatically as read-only Ghost Notes for visual reference without mixing note data or instrument parameters.

md/42_FIX_DOUBLEINST.md

@@ -0,0 +1,120 @@
+# DIAGNOSIS & BUG FIX: ENABLING ARM ON TRACK 1 CAUSES TRACK 1 INSTRUMENT TO OVERRIDE TRACK 2
+
+---
+
+## 1. ROOT CAUSE ANALYSIS
+
+The issue where arming Track 1 causes Track 1's instrument to override or mute Track 2 stems from two common architectural bugs:
+
+### 🔴 Cause 1: MIDI Channel Collision (Most Common)
+
+* **Current State:** Both Track 1 and Track 2 share the default MIDI Channel (`Channel 0`) on the Synth Engine (`SpessaSynth` / `FluidSynth`).
+* **Bug Sequence:**
+1. Initially, Track 2 assigns its instrument patch to `Channel 0`.
+2. When you arm Track 1, the UI issues a patch change command: `selectInstrument(channel = 0, bank_track1, program_track1)`.
+3. This call **overwrites** `Channel 0`'s instrument patch with Track 1's instrument.
+4. When the Timeline plays back over Track 2, Track 2 still reads notes on `Channel 0`. Consequently, all notes on Track 2 play using Track 1's instrument sound, or get muted completely if the voice allocation limit is exceeded.
+
+
+
+### 🔴 Cause 2: Hardcoded Live MIDI Channel Handler
+
+* When pressing keys on a hardware MIDI Keyboard, the `onmidimessage` handler sends a fixed `noteOn(0, pitch, velocity)` call to `Channel 0`.
+* If Track 1 is armed and triggers `programChange(0, prog1)` while Track 2 on the timeline also feeds notes into `Channel 0`, live previews and timeline playback collide on the exact same audio channel.
+
+---
+
+## 2. TECHNICAL SOLUTION & FIX CODEBASE
+
+To allow two tracks to play completely distinct instruments simultaneously—even with ARM Live Monitoring active—the system must enforce **Dedicated MIDI Channel Binding**:
+
+### Step 1: Assign an Independent MIDI Channel Per Track (`sessionStore`)
+
+During initialization or when adding a track to the session, allocate a distinct MIDI channel (from 0 to 15) to each track:
+
+```javascript
+// Assigns a dedicated MIDI Channel based on the Track's index in the session
+export function getDedicatedMIDIChannel(trackIndex) {
+  // Channel 9 (10th channel) is reserved for Percussion/Drums
+  if (trackIndex === 9) return 10; 
+  return trackIndex % 16;
+}
+
+```
+
+### Step 2: Update Patch Selection Commands to Target Only the Assigned Track Channel
+
+When selecting an instrument or when Track 1 is armed, apply patch changes exclusively to Track 1's assigned MIDI channel:
+
+```javascript
+// app/static/js/services/soundfontPlayer.js
+
+export function setTrackInstrument(track, trackIndex, soundEngine) {
+  const dedicatedChannel = getDedicatedMIDIChannel(trackIndex);
+  const synthConfig = track.synth_engine || {};
+
+  const bank = synthConfig.soundfont_bank || 0;
+  const program = synthConfig.soundfont_program || 0;
+
+  // Change patch ONLY on this track's assigned channel; do NOT touch other channels
+  soundEngine.selectInstrument(dedicatedChannel, bank, program);
+  
+  console.log(`[DAW Router] Track "${track.name}" mapped to Channel ${dedicatedChannel} (Bank:${bank}, Program:${program})`);
+}
+
+```
+
+### Step 3: Route Live Hardware MIDI Keyboard Signals to the Armed Track's Assigned Channel
+
+When the hardware MIDI keyboard emits events, identify the currently armed track and route `noteOn` / `noteOff` messages directly to that track's designated MIDI channel:
+
+```javascript
+// app/static/js/services/midiHandler.js
+
+export function handleLiveMIDIMessage(event, sessionState, soundEngine) {
+  if (!event || !event.data || event.data.length < 3) return;
+
+  const [statusByte, pitch, velocityByte] = event.data;
+  const command = statusByte >> 4;
+
+  // 1. Locate the currently ARMED [R] track on the UI
+  const armedTrackIndex = sessionState.main_session.tracks.findIndex(t => t.is_armed);
+  
+  if (armedTrackIndex === -1) {
+    // No track armed -> Suppress live preview
+    return; 
+  }
+
+  // 2. Resolve the dedicated MIDI channel for the armed track
+  const targetChannel = getDedicatedMIDIChannel(armedTrackIndex);
+
+  // 3. Route live Note On / Note Off messages to the resolved target channel
+  if (command === 0x9 && velocityByte > 0) {
+    soundEngine.noteOn(targetChannel, pitch, velocityByte / 127.0);
+  } else if (command === 0x8 || (command === 0x9 && velocityByte === 0)) {
+    soundEngine.noteOff(targetChannel, pitch);
+  }
+}
+
+```
+
+---
+
+## 3. STANDARD AUDIO ROUTING MATRIX
+
+| Object / Criteria | Track 1 (Violin) | Track 2 (Piano) |
+| --- | --- | --- |
+| **ARM State** | 🔴 ARMED (ON) | ⚪ DISARMED (OFF) |
+| **Assigned MIDI Channel** | `Channel 0` | `Channel 1` |
+| **Synth Command** | `selectInstrument(ch=0, bank=0, prog=40)` | `selectInstrument(ch=1, bank=0, prog=0)` |
+| **Live Keyboard Source** | Keypress on SE49 $\rightarrow$ `noteOn(ch=0, pitch, vel)` | Does not receive live key events |
+| **Timeline Play Source** | Emits notes from Item 1 $\rightarrow$ `noteOn(ch=0)` | Emits notes from Item 2 $\rightarrow$ `noteOn(ch=1)` |
+| **Audio Output Result** | Smooth Violin output | Simultaneous Piano output without voice overriding |
+
+---
+
+## 4. VERIFICATION & BUG FIX CHECKLIST
+
+* [ ] Console logs on project load confirm that Track 1 and Track 2 reside on separate channels (`Channel 0` and `Channel 1`).
+* [ ] Arming Track 1 $\rightarrow$ Playing keys on SE49 outputs Track 1's instrument sound.
+* [ ] Pressing Timeline Play $\rightarrow$ Track 2 outputs its assigned instrument sound on `Channel 1` in parallel with Track 1.

md/43_DS_STUPID.md

@@ -0,0 +1,132 @@
+# Fix: MAIN SESSION & SECTION-TAB Mouse Behavior (MOUSE.md)
+
+## Mô tả
+Kiểm tra và sửa các lỗi trong MAIN SESSION và SECTION-TAB theo đặc tả [MOUSE.md](file:///home/locpham/SonicForgeStudio/md/MOUSE.md):
+
+| Hành động | Đặc tả MOUSE.md |
+|---|---|
+| Click item | select item, drag to move |
+| Ctrl+Click item | toggle selection (add/remove from group) |
+| Ctrl+Click empty | deselect all |
+| Ctrl+Click+Drag item/group | **copy** item/group to new track |
+| Ctrl+Click+Drag empty | marquee selection/deselection |
+
+---
+
+## Bugs đã tìm thấy
+
+### Bug 1 – `handleSetPendingDrag`: luôn thêm `itemId` vào `ids`, bất kể đã toggle hay deselect
+**Vị trí**: [app.jsx L11834-11837](file:///home/locpham/SonicForgeStudio/app/static/js/app.jsx#L11834-L11837)
+
+```js
+const handleSetPendingDrag = (trackId, itemType, itemId, clickOffset, e, preToggleSnapshot) => {
+  var ids = preToggleSnapshot || new Set(selectedItemIds);
+  ids.add(itemId);  // ← luôn ADD itemId, bất kể đây là lần toggle-off
+  pendingDragRef.current = { ... };
+};
+```
+
+- Khi user **Ctrl+Click** vào một item đang được selected → item đó bị deselect (line 1107).  
+- Nhưng `preToggleSnapshot` (được build **trước** toggle tại line 1111/1178) luôn được `ids.add(itemId)`, nên pendingDrag vẫn include item đó trong nhóm copy.
+- **Kết quả**: Ctrl+Drag sau deselect vẫn copy item bị deselect → số lượng copies bị lỗi.
+
+**Fix**: Khi pendingDrag được set sau toggle, nếu item bị deselect (tức `preToggleSnapshot.has(itemId)`) thì **xóa** `itemId` khỏi ids thay vì add.
+
+Caller (line 1111) truyền `preToggleSnapshot` (snapshot TRƯỚC toggle), nên logic cần:
+```js
+// Nếu item đang có trong snapshot (tức là toggle-off / deselect), xóa khỏi ids
+// Nếu item không có trong snapshot (tức là toggle-on / add), thêm vào ids
+if (preToggleSnapshot && preToggleSnapshot.has(itemId)) {
+  ids.delete(itemId);
+} else {
+  ids.add(itemId);
+}
+```
+
+---
+
+### Bug 2 – `handleSectionItemDragStart` với `isDuplicate=true`: `newOriginals` bị build bên trong callback async của `updateActiveTracks`
+
+**Vị trí**: [app.jsx L11888-11924](file:///home/locpham/SonicForgeStudio/app/static/js/app.jsx#L11888-L11924)
+
+```js
+var newOriginals = {};
+updateActiveTracks(function(prev) {
+  return prev.map(function(t) {
+    // ... build newOriginals ở đây (bên trong callback)
+    newOriginals[newId] = { ... };
+    return { ...t, ... };
+  });
+});
+// Sử dụng newOriginals NGAY SAU updateActiveTracks (có thể chưa được fill)
+var newItemId = Object.keys(newOriginals)[0] || itemId;
+setDraggedSectionItem({ ..., itemId: newItemId, multiIds: newOriginals });
+```
+
+Vì `updateActiveTracks` gọi setState (React batch), callback của nó được gọi đồng bộ (React's setState updater function chạy đồng bộ). Nhưng vì `newOriginals` được closure-captured bên trong callback, điều này **thực ra hoạt động đúng** trong React 18 với batching. 
+
+Tuy nhiên: nếu **nhiều items có cùng loại** (section + midiItem + clip), vòng lặp qua `Object.keys(multiIds)` gọi `Date.now()` nhiều lần trong cùng một tick → có thể cho **cùng một newId** cho các items khác nhau, dẫn đến items bị merge.
+
+**Fix**: Thêm index counter vào ID tạo để đảm bảo unique:
+```js
+var dupCounter = 0;
+var newId = 'sec_dup_' + Date.now() + '_' + (dupCounter++) + '_' + Math.random()...
+```
+
+---
+
+### Bug 3 – Section-only path trong `isDuplicate` (non-multi): không xử lý `clip` type
+**Vị trí**: [app.jsx L11925-11938](file:///home/locpham/SonicForgeStudio/app/static/js/app.jsx#L11925-L11938)
+
+Khi không có `multiIds` (chỉ 1 item đơn lẻ), code chỉ handle `section` và `midiItem`:
+```js
+var items = itemType === 'section' ? (track.sections || []) : (track.midiItems || []);
+```
+
+Nếu `itemType === 'clip'`, `items` sẽ dùng `midiItems` (sai). Cần thêm case cho `clip`.
+
+---
+
+### Bug 4 – Ctrl+Click trên CLIP ở line 1172: điều kiện kiểm tra bỏ qua hitItem
+**Vị trí**: [app.jsx L1172](file:///home/locpham/SonicForgeStudio/app/static/js/app.jsx#L1172)
+
+```js
+if (clickedClip && (e.altKey || e.ctrlKey)) { ... }
+```
+
+Đoạn này xử lý Ctrl+Click trên **audio clip**. Tuy nhiên ở trên (line 1101), block `if (hitItem && !e.altKey && !e.shiftKey)` đã `return` nếu hitItem (section/midiItem) được click với Ctrl. Nhưng nếu không có hitItem và không có clickedClip, flow đúng (sweep select). Không có lỗi ở đây.
+
+---
+
+### Bug 5 – `handleSetPendingDrag` cho Clip (line 1184): cùng vấn đề như Bug 1
+
+Tương tự Bug 1, khi Ctrl+Click trên clip đang selected (sẽ bị deselect ở line 1180), nhưng `clipPreToggleSnapshot.has(clipCanonicalId)` là true và `ids.add(clipCanonicalId)` vẫn được thực thi trong `handleSetPendingDrag`.
+
+---
+
+## Proposed Changes
+
+### [MODIFY] [app.jsx](file:///home/locpham/SonicForgeStudio/app/static/js/app.jsx)
+
+#### Fix Bug 1 & 5 – `handleSetPendingDrag` (L11834-11838)
+Sửa logic toggle để đúng: nếu item **có** trong preToggleSnapshot → nó vừa bị deselect → **xóa** khỏi ids. Nếu không có → vừa được add → **thêm** vào ids.
+
+#### Fix Bug 2 – ID uniqueness trong multi-copy loop
+Thêm counter index vào ID generation trong vòng lặp `Object.keys(multiIds).forEach`.
+
+#### Fix Bug 3 – Single-item copy: xử lý `clip` type
+Trong nhánh `else` (non-multiIds) của `isDuplicate`, thêm xử lý `clip` type.
+
+---
+
+## Verification Plan
+
+### Manual Verification
+1. Mở MAIN SESSION
+2. Thêm vài sections/MIDI items trên nhiều tracks
+3. **Test Ctrl+Click toggle**: Click vào item A → selected. Ctrl+Click A → deselected. Ctrl+Click B → B selected (không phải A+B).
+4. **Test Ctrl+Drag single**: Ctrl+Click item → drag → chỉ copy 1 item, không thêm item nào bị deselect
+5. **Test Ctrl+Drag group**: Ctrl+Click A, Ctrl+Click B (2 selected) → drag từ A → copy cả A và B, không thêm C hay D
+6. **Test Ctrl+Click empty**: Click trống → deselect all
+7. **Test Ctrl+Drag empty**: Drag trên empty → marquee select
+8. Lặp lại trên SECTION-TAB (session_xxx)

md/44_MIXER_EQUALIZER.md

@@ -0,0 +1,532 @@
+# TECHNICAL SPECIFICATION & SYSTEM ARCHITECTURE FOR MAIN SESSION AND SECTION-TAB MIXER
+
+This document details the implementation of a docked Mixer Console (Mixer Control Panel - MCP) positioned at the bottom of the screen (similar to REAPER), alongside the hierarchical audio signal routing architecture when SECTION-TABs are nested within MAIN SESSION tracks.
+
+---
+
+## 1. HIERARCHICAL AUDIO SIGNAL ROUTING ARCHITECTURE
+
+To allow a SECTION-TAB to maintain an independent mix while assigning final master control of its output to a single track in the MAIN SESSION, the system employs a **Sub-Mix Bus Piping** model via the Web Audio API.
+
+### Audio Signal Graph Tree
+
+```text
+[ SECTION-TAB (Sub-Session) ]
+ ├── Track S1 (Audio/MIDI) ──► Gain ──► Pan ──┐
+ ├── Track S2 (Audio/MIDI) ──► Gain ──► Pan ──┼──► [ SECTION SUB-MIX BUS ]
+ └── Track S3 (Audio/MIDI) ──► Gain ──► Pan ──┘           │ (Section Master Out)
+                                                          │
+                                                          ▼ (Piped to host track)
+[ MAIN SESSION (Root Session) ]                           │
+ ├── Track 1 (Normal Audio) ──► Gain ──► Pan ─────────────┼──┐
+ ├── Track 2 (SECTION ITEM Track) ◄───────────────────────┘  │
+ │     └─ Gain Node ──► FX Chain ──► Pan Node ───────────────┼──► [ MAIN MASTER BUS ]
+ └── Track 3 (Normal MIDI)  ──► Gain ──► Pan ─────────────┘           │
+                                                                       ▼
+                                                          [ AudioContext Destination ]
+                                                               (Speakers / Soundcard)
+
+```
+
+### Audio Routing Principles:
+
+* **Inside SECTION-TAB:** Internal tracks ($S1, S2, S3$) are balanced via volume, pan, and Mute/Solo controls on the SECTION-TAB's dedicated mixer. Output signals from these tracks are summed at the `Section Sub-Mix Bus Node`.
+* **Routing to MAIN SESSION:** The output of the `Section Sub-Mix Bus Node` does not connect directly to `audioCtx.destination`. Instead, it routes into the Input Node of Track 2 on the MAIN SESSION (the track hosting the `SECTION_ITEM`).
+* **MAIN SESSION Management:**
+* The Volume Fader on Track 2 of the MAIN SESSION controls the overall volume of the entire SECTION-TAB.
+* Mute, Solo, and FX Chain controls on Track 2 of the MAIN SESSION directly process all audio originating from that SECTION-TAB before it reaches the Main Master Bus.
+
+
+
+---
+
+## 2. DOCKED MIXER CONSOLE (MCP) UI STRUCTURE
+
+The Mixer Console is designed as a docked panel underneath the Timeline, split into two main sections: **Master Channel Strip** (Left) and **Track Channel Strips** (Right).
+
+```text
++------------------------------------------------------------------------------------------------+
+| DOCKED MIXER CONSOLE                                                                           |
++-------------------+----------------------------------------------------------------------------+
+| MASTER STRIP      | TRACK CHANNEL STRIPS (Track 1, Track 2 [SECTION], Track 3...)              |
+|                   |                                                                            |
+|   (Knob) Pan      |   (Knob) Pan         (Knob) Pan         (Knob) Pan         (Knob) Pan      |
+|   [MONO]          |   -inf dB            -inf dB            -inf dB            -inf dB         |
+|   [M]  [S]        |   [M]   [S]          [M]   [S]          [M]   [S]          [M]   [S]       |
+|   [ROUTE]         |   [|||] [|||] Peak   [|||] [|||] Peak   [|||] [|||] Peak   [|||] [|||] Peak|
+|   [FX] [Power]    |   [===] Fader        [===] Fader        [===] Fader        [===] Fader     |
+|   [TRIM]          |   [FX]  [Power]      [FX]  [Power]      [FX]  [Power]      [FX]  [Power]   |
+|   [FADER] (VU)    |   [🔴]   [ROUTE]     [🔴]   [ROUTE]     [🔴]   [ROUTE]     [🔴]   [ROUTE]   |
+|                   |   ------------------ ------------------ ------------------ ----------------|
+|   RMS/Peak Meter  |   Track 1 (Kick)     Track 2 (SECTION)  Track 3 (Guitars)  Track 4 (Lead)  |
+|   MASTER          |   [🎵 SF2 Synth]     [📦 Sec: Chorus]   [🎸 Pedalboard]    [🎹 Vital]      |
++-------------------+----------------------------------------------------------------------------+
+
+```
+
+### Channel Strip Components:
+
+* **Top Pan Knob:** Rotatable control for Left/Right stereo balance (Pan Left/Right, $-1.0$ to $+1.0$).
+* **Numeric dB Readout:** Displays current volume level in numeric dB (e.g., $0.0\text{ dB}$, $-6.5\text{ dB}$, $-inf$).
+* **Mute [M] & Solo [S] Buttons:**
+* Orange **[M]** button: Mutes track output.
+* Yellow **[S]** button: Solos track output (mutes all non-soloed tracks).
+
+
+* **Vertical Level Meter (VU Peak Meter):** Real-time LED signal amplitude meter (Green $\rightarrow$ Yellow $\rightarrow$ Red clipping indicator above $0\text{ dBFS}$).
+* **Volume Fader Slider:** Vertical linear slider for gain control.
+* **FX & Power Toggle:**
+* **[FX]** button: Opens the Effects Plugin management window (Reverb, Delay, EQ, Compressor).
+* **[Power]** button: Toggles bypass state for the track's entire FX chain.
+
+
+* **Record Arm [🔴] & Routing/Trim Buttons:**
+* Red circle **[🔴]**: Arms track for recording.
+* **[ROUTE]** button: Opens the Input/Output Matrix configuration panel.
+
+
+* **Track Identifier Footer:** Displays track index ($1, 2, 3...$) and track name (e.g., *Track 2 - Chorus Section*).
+
+---
+
+## 3. STATE STORE SCHEMAS
+
+### 3.1 Main Session State (`main_session_mixer_state`)
+
+```json
+{
+  "session_id": "main_session_root",
+  "master_bus": {
+    "volume_db": 0.0,
+    "pan": 0.0,
+    "mute": false,
+    "is_mono": false,
+    "fx_chain": []
+  },
+  "tracks": [
+    {
+      "id": "track_01",
+      "name": "Track 1 - Drums",
+      "type": "AUDIO",
+      "volume_db": -2.5,
+      "pan": 0.0,
+      "mute": false,
+      "solo": false,
+      "is_armed": false
+    },
+    {
+      "id": "track_02_section_host",
+      "name": "Track 2 - Chorus Section",
+      "type": "SECTION",
+      "volume_db": 0.0,
+      "pan": 0.0,
+      "mute": false,
+      "solo": false,
+      "referenced_section_id": "section_chorus_001"
+    }
+  ]
+}
+
+```
+
+### 3.2 Section-Tab State (`section_store`)
+
+```json
+{
+  "section_store": {
+    "section_chorus_001": {
+      "id": "section_chorus_001",
+      "name": "Chorus Section Tab",
+      "is_root": false,
+      "parent_track_id": "track_02_section_host",
+      "sub_mix_bus": {
+        "volume_db": 0.0,
+        "pan": 0.0,
+        "mute": false,
+        "fx_chain": []
+      },
+      "tracks": [
+        {
+          "id": "sec_track_1",
+          "name": "Sec Guitar 1",
+          "volume_db": -1.0,
+          "pan": -0.5,
+          "mute": false,
+          "solo": false
+        },
+        {
+          "id": "sec_track_2",
+          "name": "Sec Vocal Lead",
+          "volume_db": +1.5,
+          "pan": 0.0,
+          "mute": false,
+          "solo": false
+        }
+      ]
+    }
+  }
+}
+
+```
+
+---
+
+## 4. AUDIO GRAPH NODE ENGINE (WEB AUDIO API)
+
+To execute audio summing according to the architecture above, the application uses a manager class to maintain Web Audio nodes (`AudioNode Graph`):
+
+```javascript
+// app/static/js/services/audioMixerGraphManager.js
+
+export class AudioMixerGraphManager {
+  constructor(audioCtx) {
+    this.audioCtx = audioCtx;
+    
+    // Main Session Master Nodes
+    this.mainMasterGain = this.audioCtx.createGain();
+    this.mainMasterPan = this.audioCtx.createStereoPanner();
+    this.mainMasterAnalyser = this.audioCtx.createAnalyser();
+
+    // Connect Master Graph -> Speakers
+    this.mainMasterGain
+      .connect(this.mainMasterPan)
+      .connect(this.mainMasterAnalyser)
+      .connect(this.audioCtx.destination);
+
+    // Map storing track AudioNodes
+    this.trackNodesMap = new Map();     // trackId -> { inputGain, faderGain, panNode, analyserNode }
+    this.sectionBusesMap = new Map();   // sectionId -> { subMixGain, subMixPan, outputNode }
+  }
+
+  /**
+   * Initializes Audio Nodes for a track on the Main Session
+   */
+  createMainTrackNodes(track) {
+    const inputGain = this.audioCtx.createGain();
+    const faderGain = this.audioCtx.createGain();
+    const panNode = this.audioCtx.createStereoPanner();
+    const analyserNode = this.audioCtx.createAnalyser();
+    analyserNode.fftSize = 64;
+
+    // Track internal signal chain connection:
+    // InputGain -> FaderGain -> PanNode -> Analyser -> Main Master Gain
+    inputGain
+      .connect(faderGain)
+      .connect(panNode)
+      .connect(analyserNode)
+      .connect(this.mainMasterGain);
+
+    const nodeBundle = { inputGain, faderGain, panNode, analyserNode, track };
+    this.trackNodesMap.set(track.id, nodeBundle);
+
+    // Update initial Gain/Pan values
+    this.updateTrackVolumePan(track.id, track.volume_db, track.pan, track.mute);
+    return nodeBundle;
+  }
+
+  /**
+   * Initializes a Sub-Mix Bus for a SECTION-TAB and PIPES it to a Main Session track
+   * @param {string} sectionId - Section ID
+   * @param {string} hostTrackId - Main Session Track ID hosting this section
+   */
+  createSectionSubMixBus(sectionId, hostTrackId) {
+    const subMixGain = this.audioCtx.createGain();
+    const subMixPan = this.audioCtx.createStereoPanner();
+
+    // Section Sub-Mix Bus internal connection
+    subMixGain.connect(subMixPan);
+
+    // CRITICAL STEP: Locate host track on Main Session to pipe signal
+    const hostTrackNodes = this.trackNodesMap.get(hostTrackId);
+
+    if (hostTrackNodes) {
+      // Pipe Output of Section Bus directly into InputGain of Main Track
+      subMixPan.connect(hostTrackNodes.inputGain);
+      console.log(`[MixerRouter] Sub-Mix Bus of Section "${sectionId}" successfully PIPED into Main Track "${hostTrackId}"`);
+    } else {
+      console.warn(`[MixerRouter] Host Track "${hostTrackId}" not found. Section bus falling back to Master.`);
+      subMixPan.connect(this.mainMasterGain);
+    }
+
+    const sectionBundle = { subMixGain, subMixPan, hostTrackId };
+    this.sectionBusesMap.set(sectionId, sectionBundle);
+    return sectionBundle;
+  }
+
+  /**
+   * Initializes an INTERNAL track inside a SECTION-TAB
+   */
+  createSectionTrackNodes(sectionId, secTrack) {
+    const sectionBundle = this.sectionBusesMap.get(sectionId);
+    if (!sectionBundle) {
+      throw new Error(`Section Sub-Mix Bus for "${sectionId}" has not been initialized!`);
+    }
+
+    const inputGain = this.audioCtx.createGain();
+    const faderGain = this.audioCtx.createGain();
+    const panNode = this.audioCtx.createStereoPanner();
+    const analyserNode = this.audioCtx.createAnalyser();
+
+    // Connect Track in Section to the Section's Sub-Mix Bus
+    inputGain
+      .connect(faderGain)
+      .connect(panNode)
+      .connect(analyserNode)
+      .connect(sectionBundle.subMixGain); // Direct to Section Sub-Mix Bus!
+
+    const nodeBundle = { inputGain, faderGain, panNode, analyserNode, secTrack };
+    this.trackNodesMap.set(secTrack.id, nodeBundle);
+
+    this.updateTrackVolumePan(secTrack.id, secTrack.volume_db, secTrack.pan, secTrack.mute);
+    return nodeBundle;
+  }
+
+  /**
+   * Updates Volume (dB) & Pan using standard audio formulas
+   */
+  updateTrackVolumePan(trackId, volumeDb, panValue, isMuted) {
+    const bundle = this.trackNodesMap.get(trackId);
+    if (!bundle) return;
+
+    // Convert dB to Linear Gain Factor: Gain = 10 ^ (dB / 20)
+    const linearGain = isMuted ? 0.0 : Math.pow(10, volumeDb / 20.0);
+
+    bundle.faderGain.gain.setTargetAtTime(linearGain, this.audioCtx.currentTime, 0.01);
+    bundle.panNode.pan.setTargetAtTime(panValue, this.audioCtx.currentTime, 0.01);
+  }
+}
+
+```
+
+---
+
+## 5. NESTED MUTE/SOLO LOGIC MATRIX
+
+When muting or soloing a track on the Main Session or within a Section Tab, the system applies hierarchical rules:
+
+| User Action | Main Session Impact | Internal Section Tracks Impact |
+| --- | --- | --- |
+| **Mute Track 2 (Section Host)** on Main Session | Track 2 is muted. Other tracks play normally. | Entire Section is muted (signal is blocked at Track 2's Fader Gain). |
+| **Mute Section Track 1** inside Section Tab | No impact on other Main Tracks. | Only Section Track 1 is silenced. Other Section Tracks ($S2, S3$) continue routing to Track 2. |
+| **Solo Section Track 1** inside Section Tab | No impact on Main Session. | Mutes $S2, S3$ within the Section. Only $S1$ outputs to Track 2 of the Main Session. |
+| **Solo Track 2** on Main Session | Mutes Track 1 and Track 3 on Main Session. | The Section audio stream plays normally to the Main Master Bus. |
+
+---
+
+## 6. STATE-DRIVEN REACT/CANVAS COMPONENT
+
+Below is the React implementation for the Mixer Console supporting dynamic switching between MAIN SESSION and SECTION-TAB mixers:
+
+```jsx
+// app/static/js/components/MixerConsole.jsx
+import React, { useState, useEffect } from 'react';
+
+export function MixerConsole({ sessionState, activeTabContext, mixerGraphMgr }) {
+  // Determine if Mixer is rendering for MAIN SESSION or SECTION-TAB
+  const isSectionTab = activeTabContext?.type === 'SECTION_TAB';
+  
+  // Retrieve target tracks list for Mixer Console display
+  const currentTracks = isSectionTab
+    ? sessionState.section_store[activeTabContext.referenced_section_id]?.tracks || []
+    : sessionState.main_session.tracks;
+
+  const currentTitle = isSectionTab
+    ? `MIXER: SECTION TAB (${activeTabContext.title})`
+    : "MIXER: MAIN SESSION";
+
+  return (
+    <div className="flex flex-col h-64 bg-slate-900 border-t border-slate-700 text-slate-200 select-none">
+      {/* Mixer Header / Tab Indicator */}
+      <div className="flex items-center justify-between px-3 py-1 bg-slate-950 border-b border-slate-800 text-xs font-semibold">
+        <div className="flex items-center gap-2">
+          <span className={`w-2.5 h-2.5 rounded-full ${isSectionTab ? "bg-amber-400 animate-pulse" : "bg-indigo-500"}`} />
+          <span className="text-white tracking-wide">{currentTitle}</span>
+        </div>
+        {isSectionTab && (
+          <span className="text-[10px] text-amber-300/80 bg-amber-950/60 px-2 py-0.5 rounded border border-amber-800/50">
+            Routed to Main Track: {activeTabContext.parent_track_name || "Track Host"}
+          </span>
+        )}
+      </div>
+
+      {/* Mixer Strips Container */}
+      <div className="flex-1 flex overflow-x-auto p-2 gap-1.5 custom-scrollbar bg-slate-900/90">
+        {/* 1. MASTER STRIP (Far Left) */}
+        <MasterChannelStrip
+          isSectionBus={isSectionTab}
+          mixerGraphMgr={mixerGraphMgr}
+        />
+
+        <div className="w-[1px] bg-slate-700/60 mx-1 my-1" />
+
+        {/* 2. TRACK STRIPS (Audio Channels) */}
+        {currentTracks.map((track, idx) => (
+          <TrackChannelStrip
+            key={track.id}
+            track={track}
+            index={idx + 1}
+            mixerGraphMgr={mixerGraphMgr}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Channel Strip Component representing a single Track
+ */
+function TrackChannelStrip({ track, index, mixerGraphMgr }) {
+  const [volumeDb, setVolumeDb] = useState(track.volume_db || 0);
+  const [pan, setPan] = useState(track.pan || 0);
+  const [isMuted, setIsMuted] = useState(Boolean(track.mute));
+  const [isSoloed, setIsSoloed] = useState(Boolean(track.solo));
+
+  const handleVolumeChange = (e) => {
+    const newDb = parseFloat(e.target.value);
+    setVolumeDb(newDb);
+    track.volume_db = newDb;
+    mixerGraphMgr?.updateTrackVolumePan(track.id, newDb, pan, isMuted);
+  };
+
+  const handleToggleMute = () => {
+    const newMute = !isMuted;
+    setIsMuted(newMute);
+    track.mute = newMute;
+    mixerGraphMgr?.updateTrackVolumePan(track.id, volumeDb, pan, newMute);
+  };
+
+  return (
+    <div className="w-24 bg-slate-950 border border-slate-800 rounded flex flex-col p-1.5 items-center justify-between shadow-lg">
+      {/* 1. Pan Knob */}
+      <div className="flex flex-col items-center w-full">
+        <span className="text-[10px] text-slate-400 font-mono">
+          {pan === 0 ? "center" : pan < 0 ? `L${Math.abs(Math.round(pan * 100))}` : `R${Math.round(pan * 100)}`}
+        </span>
+        <input
+          type="range"
+          min="-1"
+          max="1"
+          step="0.05"
+          value={pan}
+          onChange={(e) => {
+            const p = parseFloat(e.target.value);
+            setPan(p);
+            track.pan = p;
+            mixerGraphMgr?.updateTrackVolumePan(track.id, volumeDb, p, isMuted);
+          }}
+          className="w-12 h-1 accent-indigo-500 cursor-pointer"
+        />
+      </div>
+
+      {/* 2. dB Readout */}
+      <div className="text-[11px] font-mono text-slate-300 font-semibold my-0.5">
+        {volumeDb <= -60 ? "-inf" : `${volumeDb > 0 ? "+" : ""}${volumeDb.toFixed(1)}dB`}
+      </div>
+
+      {/* 3. Mute / Solo Buttons */}
+      <div className="flex gap-1 w-full my-1">
+        <button
+          onClick={handleToggleMute}
+          className={`flex-1 text-[10px] font-bold py-0.5 rounded border transition-colors ${
+            isMuted ? "bg-amber-600 text-white border-amber-500" : "bg-slate-800 text-slate-400 border-slate-700 hover:bg-slate-700"
+          }`}
+        >
+          M
+        </button>
+        <button
+          onClick={() => {
+            const s = !isSoloed;
+            setIsSoloed(s);
+            track.solo = s;
+          }}
+          className={`flex-1 text-[10px] font-bold py-0.5 rounded border transition-colors ${
+            isSoloed ? "bg-yellow-500 text-black border-yellow-400" : "bg-slate-800 text-slate-400 border-slate-700 hover:bg-slate-700"
+          }`}
+        >
+          S
+        </button>
+      </div>
+
+      {/* 4. Fader & Meter Section */}
+      <div className="flex-1 flex items-center justify-center gap-1.5 w-full my-1 relative">
+        {/* Fader Slider */}
+        <input
+          type="range"
+          min="-60"
+          max="12"
+          step="0.5"
+          value={volumeDb}
+          onChange={handleVolumeChange}
+          className="h-28 w-2 appearance-none bg-slate-800 rounded outline-none cursor-pointer [writing-mode:vertical-lr] [direction:rtl]"
+        />
+
+        {/* VU Peak Meter Bar */}
+        <div className="w-2.5 h-28 bg-slate-900 border border-slate-800 rounded overflow-hidden flex flex-col justify-end p-0.5">
+          <div className="w-full bg-gradient-to-t from-emerald-500 via-yellow-400 to-red-500 h-[40%]" />
+        </div>
+      </div>
+
+      {/* 5. FX & Power Buttons */}
+      <div className="flex gap-1 w-full my-1">
+        <button className="flex-1 bg-slate-800 hover:bg-slate-700 text-slate-300 text-[9px] py-0.5 rounded border border-slate-700 font-semibold">
+          FX
+        </button>
+        <button className="px-1.5 bg-slate-800 hover:bg-slate-700 text-slate-400 text-[9px] py-0.5 rounded border border-slate-700">
+          ⑈
+        </button>
+      </div>
+
+      {/* 6. Footer Name */}
+      <div className="w-full text-center bg-slate-900 py-1 rounded border border-slate-800/80 mt-1">
+        <div className="text-[10px] font-bold text-white truncate px-1">{index}. {track.name}</div>
+        <div className="text-[8px] text-slate-500 uppercase tracking-tighter truncate">{track.type}</div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Master Channel Strip Component
+ */
+function MasterChannelStrip({ isSectionBus, mixerGraphMgr }) {
+  return (
+    <div className="w-28 bg-slate-950 border-2 border-indigo-900/60 rounded flex flex-col p-1.5 items-center justify-between shadow-2xl">
+      <div className="text-[10px] font-bold text-indigo-400 uppercase tracking-wider">
+        {isSectionBus ? "SEC BUS" : "MASTER"}
+      </div>
+
+      {/* Peak / RMS Canvas Meter */}
+      <div className="w-full h-32 bg-black border border-indigo-950 rounded relative my-2 overflow-hidden flex items-center justify-center">
+        <span className="text-[9px] font-mono text-emerald-400/80 font-semibold">-inf dB</span>
+      </div>
+
+      <div className="w-full text-center bg-indigo-950/80 border border-indigo-800/60 py-1 rounded mt-auto">
+        <div className="text-[10px] font-bold text-indigo-200 uppercase">
+          {isSectionBus ? "SUB-MIX" : "MAIN OUT"}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+```
+
+---
+
+## 7. OPERATIONAL VERIFICATION CHECKLIST
+
+* [ ] **Main Session Mixer Operations:**
+* Adjust Track 1 Fader $\rightarrow$ Track 1 volume increases/decreases as expected.
+* Mute Track 1 $\rightarrow$ Track 1 output is silenced.
+
+
+* [ ] **SECTION-TAB Mixer & Routing Operations:**
+* Open a SECTION-TAB into a sub-tab $\rightarrow$ Mixer Console dynamically switches header to `MIXER: SECTION TAB` displaying internal section tracks.
+* Adjust Section Track 1 Fader $\rightarrow$ Guitar volume within the Section increases/decreases without affecting other Main Tracks.
+
+
+* [ ] **Bus Routing Point Verification:**
+* Switch back to MAIN SESSION tab.
+* Adjust Track 2 Fader (Track hosting Section Item) $\rightarrow$ Entire SECTION-TAB volume adjusts synchronously.
+* Mute Track 2 $\rightarrow$ Entire SECTION-TAB output is silenced completely.

md/45_MASTERING_MODULE.md

@@ -0,0 +1,887 @@
+# TECHNICAL SPECIFICATION & OPERATIONAL WORKFLOW MANUAL: OZONE WEB MASTERING SUITE
+
+This document compiles the complete architectural layout, module inventory, control parameter specifications, dynamic re-routing execution matrices, visual metering systems, and full single-file implementation code for the Ozone-Style Web Mastering Engine.
+
+---
+
+## 1. AUDIO PROCESSING MODULES SUMMARY
+
+| Module Name | Core Function | Web Audio API Nodes / Class | Key Control Parameters | Inherited Acoustic Impact |
+| --- | --- | --- | --- | --- |
+| **Dynamic EQ** | Dynamic frequency filtering and equalization | `BiquadFilterNode` (`lowshelf`, `peaking`, `highshelf`) | 4-Band Gain ($-12 \text{ to } +12\text{ dB}$), Frequency, Q Factor | Balances frequency spectrum, carves out harsh resonances, or boosts air/warmth dynamically without introducing harsh clipping. |
+| **Stereo Imager** | Mid/Side spatial expansion and balance | `ChannelSplitterNode`, `ChannelMergerNode`, `GainNode` | 4-Band Width ($-100\% \text{ to } +100\%$), Mid/Side Gain | Expands stereo width across High/Mid bands while collapsing Low/Sub-bass bands to Mono for maximum low-end punch. |
+| **IRC IV Maximizer** | True-Peak Limiter & Peak Gain Boosting | `WaveShaperNode` (Soft Clip), `DynamicsCompressorNode` | Boost Gain ($+0 \text{ to } +12\text{ dB}$), Soft Clip %, Upward Comp, Ceiling | Maximizes perceived loudness (LUFS) to commercial distribution standards while suppressing transient spikes below $0\text{ dBFS}$. |
+| **Master Utilities** | I/O Management, Metering & Codec Emulation | `AnalyserNode` (FFT 2048), `GainNode` | Delta Listen, Gain Match, Codec Preview, Dither | Enables objective A/B listening tests between pre/post-mastered signals, emulates lossy MP3/AAC compression, and manages bit-depth reduction. |
+
+---
+
+## 2. PARAMETER CONTROL SPECIFICATIONS MATRIX
+
+| Module Group | Parameter Name | Range | Unit | Node Handler / Formula | Technical Purpose |
+| --- | --- | --- | --- | --- | --- |
+| **Dynamic EQ** | `eqLowGain` | $-12.0 \to +12.0$ | dB | Lowshelf @ $100\text{Hz}$ | Controls low-end punch and sub-bass weight. |
+| **Dynamic EQ** | `eqMid1Gain` | $-12.0 \to +12.0$ | dB | Peaking @ $822\text{Hz}$, $Q=0.7$ | Cleans up muddy or boxy low-mid frequencies. |
+| **Dynamic EQ** | `eqMid2Gain` | $-12.0 \to +12.0$ | dB | Peaking @ $3.2\text{kHz}$, $Q=1.2$ | Adjusts vocal clarity and instrument presence. |
+| **Dynamic EQ** | `eqHighGain` | $-12.0 \to +12.0$ | dB | Highshelf @ $10\text{kHz}$ | Adds high-frequency air, sheen, and sparkle. |
+| **Stereo Imager** | `w1` (Band 1) | $-100 \to +100$ | % | Mid/Side Gain ($0-100\text{Hz}$) | Collapses sub-bass to mono ($0\%$) to ensure club system compatibility. |
+| **Stereo Imager** | `w2` (Band 2) | $-100 \to +100$ | % | Mid/Side Gain ($100\text{Hz}-1\text{kHz}$) | Balances body and width for core instruments. |
+| **Stereo Imager** | `w3` (Band 3) | $-100 \to +100$ | % | Mid/Side Gain ($1\text{kHz}-6\text{kHz}$) | Expands upper-mid imaging for a wider soundstage. |
+| **Stereo Imager** | `w4` (Band 4) | $-100 \to +100$ | % | Mid/Side Gain ($6\text{kHz}-20\text{kHz}$) | Widens top-end spatial atmosphere. |
+| **Maximizer** | `maxGain` | $0.0 \to +12.0$ | dB | Gain Boost Node | Drives the signal into the limiter to increase overall LUFS. |
+| **Maximizer** | `maxUpward` | $0.0 \to +10.0$ | dB | Dynamic Range Expander | Brings up low-level details for a denser mix. |
+| **Maximizer** | `maxSoftClip` | $0 \to 100$ | % | Arctan WaveShaper Curve | Rounds off sharp transient peaks to add analog-style saturation. |
+| **Maximizer** | `ceiling` | $-6.0 \to 0.0$ | dBFS | Brickwall Limiter Threshold | Absolute ceiling threshold (Default: $-0.10\text{ dBFS}$). |
+
+---
+
+## 3. AUDIONODE GRAPH RE-ROUTING EVENT MATRIX
+
+| UI Action | Triggered Event | Audio Engine Method (`OzoneAudioChainManager`) | Node Graph Execution | Perceived Acoustic Effect |
+| --- | --- | --- | --- | --- |
+| **Add Module (`[+] Add`)** | Click Add Module button | `addModuleToChain(moduleName)` | Appends module to `moduleChain`, disconnects existing routing, and re-connects all nodes in sequence. | Introduces additional processing step to the signal chain prior to Master Out. |
+| **Remove Module (`[x] Remove`)** | Click Remove Module button | `removeModuleFromChain(moduleName)` | Filters module out of `moduleChain`, disconnects old connections, and connects remaining nodes directly. | Bypasses the removed module's processing, reducing latency and CPU load. |
+| **Reorder Chain** | Drag & Drop Module Card | `reorderChain(newArray)` | Disconnects the entire graph and rebuilds connections from scratch based on the new array order. | Alters processing order (e.g., Stereo Imager widening prior to EQ vs. post-EQ). |
+| **Toggle Module Power** | Click Module Power button | `state.moduleActive = !active; updateAudioParameters();` | Sets target band gains to $0\text{ dB}$ or bypasses signal around module. | Passes signal through the target module without tonal modification (flat response). |
+| **Master Bypass** | Click Master Bypass button | `toggleMasterBypass()` | Reroutes input directly: `inputAnalyser` $\to$ `masterBypassGain` $\to$ `outputAnalyser`. | Instantly returns signal to raw, unprocessed dry audio for A/B comparison. |
+
+---
+
+## 4. GRAPHICAL METERS & VISUALIZER CANVAS SYSTEMS
+
+| Visualizer Canvas | Source Audio Node | Rendering Math / Algorithm | Graphical Characteristics & Refresh Rate |
+| --- | --- | --- | --- |
+| **Dynamic EQ Spectrum** | `outputAnalyser.getByteFrequencyData()` | Logarithmic Frequency Scaling ($20\text{Hz} - 20\text{kHz}$) | Cyan composite EQ curve overlaid across a live 60 FPS FFT frequency spectrum fill. |
+| **Polar Vectorscope** | Channel Splitter (Independent L/R Signals) | Polar Coordinate Calculation ($\theta = \arctan(R/L)$, radius $r$) | 180° radial particle scatter plot depicting phase correlation and stereo width. |
+| **I/O Stereo VU Meters** | `inputAnalyser` & `outputAnalyser` | Peak Calculation ($dB = 20 \log_{10}(\text{level})$) using Time-Domain data | Vertical Green $\to$ Yellow $\to$ Red gradient meters with real-time numeric dBFS readouts. |
+
+---
+
+## 5. MASTER UTILITIES COMPARISON
+
+| Utility Feature | DSP Mechanism / Formula | Operational Purpose in Mastering |
+| --- | --- | --- |
+| **Delta Listen (`[i] Delta`)** | $S_{\text{Delta}}(t) = S_{\text{Input}}(t) - S_{\text{Output}}(t)$ | Isolates the exact signal difference being removed or compressed to prevent over-processing. |
+| **Gain Match** | $G_{\text{Match}} = \text{LUFS}_{\text{Input}} - \text{LUFS}_{\text{Output}}$ | Automatically matches output loudness to input level to enable objective A/B evaluations free from "louder is better" bias. |
+| **Codec Preview** | Low-pass Biquad Filter @ $16\text{kHz}$ | Simulates lossy high-frequency roll-off typical of 128 kbps MP3/AAC encoding. |
+| **Dither Processor** | Triangular PDF Noise Injection | Prevents quantization distortion when converting bit-depth from 32-bit Float down to 16-bit PCM. |
+
+---
+
+## 6. FULL SINGLE-FILE IMPLEMENTATION CODE
+
+Below is the complete single-file source code incorporating HTML5, Tailwind CSS, FontAwesome, HTML5 Canvas, and Web Audio API DSP engines modeling the iZotope Ozone mastering interface:
+
+```html
+<!DOCTYPE html>
+<html lang="en" class="h-full bg-slate-950 text-slate-100 select-none">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Ozone Mastering Studio Engine</title>
+  <!-- Tailwind CSS -->
+  <script src="https://cdn.tailwindcss.com"></script>
+  <!-- Font Awesome -->
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+  <!-- Fonts -->
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet">
+  
+  <style>
+    body { font-family: 'Inter', sans-serif; }
+    .font-mono { font-family: 'JetBrains Mono', monospace; }
+    
+    ::-webkit-scrollbar { width: 4px; height: 4px; }
+    ::-webkit-scrollbar-track { background: #080b12; }
+    ::-webkit-scrollbar-thumb { background: #1e293b; border-radius: 2px; }
+    ::-webkit-scrollbar-thumb:hover { background: #334155; }
+
+    .knob-container { touch-action: none; user-select: none; }
+    .knob-dial {
+      transition: transform 0.05s ease-out;
+      box-shadow: inset 0 1px 3px rgba(255,255,255,0.15), 0 3px 8px rgba(0,0,0,0.8);
+    }
+    
+    /* Ozone Theme Dark Gradient Panels */
+    .oz-panel {
+      background: linear-gradient(180deg, #131822 0%, #0d1118 100%);
+      border: 1px solid rgba(255, 255, 255, 0.07);
+    }
+    .oz-card {
+      background: #18202c;
+      border: 1px solid rgba(255, 255, 255, 0.1);
+    }
+    .oz-card-active {
+      background: #1e2a3a;
+      border-color: #38bdf8;
+      box-shadow: 0 0 12px rgba(56, 189, 248, 0.2);
+    }
+  </style>
+</head>
+<body class="h-full flex flex-col overflow-hidden bg-slate-950 text-slate-200">
+
+  <!-- TOP TRANSPORT & SESSION BAR -->
+  <header class="h-12 bg-slate-900/90 border-b border-slate-800/80 flex items-center justify-between px-4 z-30">
+    <div class="flex items-center gap-3">
+      <div class="w-7 h-7 rounded-lg bg-cyan-600 flex items-center justify-center font-bold text-white shadow-lg shadow-cyan-950">
+        <i class="fa-solid fa-atom text-xs"></i>
+      </div>
+      <div>
+        <h1 class="text-xs font-bold tracking-wider text-white flex items-center gap-2">
+          OZONE ADVANCED <span class="text-[9px] bg-cyan-950 text-cyan-400 border border-cyan-800/80 px-1.5 py-0.5 rounded font-mono">WEB MASTERING V10.5</span>
+        </h1>
+      </div>
+    </div>
+
+    <!-- Central Signal Generator & Transport -->
+    <div class="flex items-center gap-3 bg-slate-950 px-3 py-1 rounded-lg border border-slate-800/80">
+      <button id="playAudioBtn" class="px-3 py-1 bg-cyan-600 hover:bg-cyan-500 text-white rounded text-xs font-semibold flex items-center gap-1.5 transition-all shadow-md shadow-cyan-950">
+        <i class="fa-solid fa-play text-[10px]"></i> <span>Play Reference Loop</span>
+      </button>
+      <button id="stopAudioBtn" class="px-3 py-1 bg-slate-800 hover:bg-slate-700 text-slate-300 rounded text-xs font-semibold flex items-center gap-1.5 transition-all">
+        <i class="fa-solid fa-stop text-[10px]"></i> <span>Stop</span>
+      </button>
+
+      <div class="h-4 w-[1px] bg-slate-800 mx-1"></div>
+
+      <div class="flex items-center gap-2 text-xs font-mono">
+        <span class="text-slate-400 text-[11px]">Preset:</span>
+        <select id="masterPresetSelect" class="bg-slate-900 border border-slate-700 rounded px-2 py-0.5 text-xs text-cyan-300 outline-none focus:border-cyan-500">
+          <option value="adaptive">Adaptive Dynamic Master</option>
+          <option value="edm_club">EDM / Club Punch Maximizer</option>
+          <option value="wide_space">Cinematic Stereo Expansion</option>
+          <option value="transparent">Transparent High-Clarity Limiter</option>
+        </select>
+      </div>
+    </div>
+
+    <!-- Right Target Meter Info -->
+    <div class="flex items-center gap-3 text-xs font-mono">
+      <span class="text-slate-400 text-[11px]">Target LUFS:</span>
+      <span id="targetLufsText" class="text-cyan-400 font-bold bg-slate-950 border border-cyan-900/60 px-2 py-0.5 rounded">-11.0 LUFS</span>
+    </div>
+  </header>
+
+  <!-- MODULE RACK STRIP (OZONE UPPER MODULE BAR) -->
+  <div class="h-16 bg-slate-950 border-b border-slate-800 px-4 flex items-center gap-2 overflow-x-auto">
+    <span class="text-[10px] font-bold text-slate-500 uppercase tracking-widest mr-1 font-mono">MODULE CHAIN:</span>
+
+    <!-- Module 1: Dynamic EQ Card -->
+    <div id="cardDynamicEq" class="oz-card oz-card-active w-36 h-12 rounded-lg p-2 flex items-center justify-between cursor-pointer transition-all">
+      <div class="flex items-center gap-2">
+        <button id="toggleEqBtn" class="w-4 h-4 rounded-full bg-cyan-500 hover:bg-cyan-400 text-slate-950 flex items-center justify-center text-[9px] font-bold">
+          <i class="fa-solid fa-power-off"></i>
+        </button>
+        <div>
+          <div class="text-[11px] font-bold text-slate-200">Dynamic EQ</div>
+          <div class="text-[9px] text-cyan-400 font-mono">4-Band Peak</div>
+        </div>
+      </div>
+      <i class="fa-solid fa-chart-area text-slate-500 text-xs"></i>
+    </div>
+
+    <!-- Module 2: Stereo Imager Card -->
+    <div id="cardImager" class="oz-card w-36 h-12 rounded-lg p-2 flex items-center justify-between cursor-pointer transition-all">
+      <div class="flex items-center gap-2">
+        <button id="toggleImagerBtn" class="w-4 h-4 rounded-full bg-cyan-500 hover:bg-cyan-400 text-slate-950 flex items-center justify-center text-[9px] font-bold">
+          <i class="fa-solid fa-power-off"></i>
+        </button>
+        <div>
+          <div class="text-[11px] font-bold text-slate-200">Imager</div>
+          <div class="text-[9px] text-slate-400 font-mono">4-Band Width</div>
+        </div>
+      </div>
+      <i class="fa-solid fa-circle-nodes text-slate-500 text-xs"></i>
+    </div>
+
+    <!-- Module 3: Maximizer Card -->
+    <div id="cardMaximizer" class="oz-card w-36 h-12 rounded-lg p-2 flex items-center justify-between cursor-pointer transition-all">
+      <div class="flex items-center gap-2">
+        <button id="toggleMaximizerBtn" class="w-4 h-4 rounded-full bg-cyan-500 hover:bg-cyan-400 text-slate-950 flex items-center justify-center text-[9px] font-bold">
+          <i class="fa-solid fa-power-off"></i>
+        </button>
+        <div>
+          <div class="text-[11px] font-bold text-slate-200">Maximizer</div>
+          <div class="text-[9px] text-slate-400 font-mono">IRC IV True Peak</div>
+        </div>
+      </div>
+      <i class="fa-solid fa-gauge-high text-slate-500 text-xs"></i>
+    </div>
+
+    <!-- Empty Add Module Slot -->
+    <div class="w-24 h-12 rounded-lg border border-dashed border-slate-800 flex items-center justify-center text-slate-600 hover:text-slate-400 hover:border-slate-600 cursor-pointer transition-all">
+      <i class="fa-solid fa-plus text-sm"></i>
+    </div>
+  </div>
+
+  <!-- MAIN WORKSPACE CONTAINER -->
+  <main class="flex-1 flex overflow-hidden">
+    
+    <!-- LEFT MODULE WORKSPACE (DYNAMIC VISUALIZER & CONTROLS) -->
+    <div class="flex-1 flex flex-col bg-slate-950 relative overflow-y-auto">
+      
+      <!-- SUB HEADER TOOLBAR -->
+      <div class="h-9 bg-slate-900/60 border-b border-slate-800/80 px-4 flex items-center justify-between text-xs font-mono">
+        <div class="flex items-center gap-3">
+          <span class="text-slate-400 flex items-center gap-1.5"><i class="fa-solid fa-headphones text-cyan-400"></i> Delta Listen</span>
+          <select id="modeSelect" class="bg-slate-950 border border-slate-800 rounded px-2 py-0.5 text-[11px] text-slate-300 outline-none">
+            <option value="irc4">IRC IV - Classic</option>
+            <option value="irc3">IRC III - Balanced</option>
+            <option value="irc2">IRC II - Crisp</option>
+          </select>
+        </div>
+
+        <div class="flex items-center gap-2 text-[11px]">
+          <span class="text-slate-400">Learn Input Gain:</span>
+          <button id="learnGainBtn" class="bg-cyan-950 text-cyan-300 border border-cyan-800/80 px-2 py-0.5 rounded font-bold hover:bg-cyan-900 transition-colors">
+            -11.0 LUFS
+          </button>
+        </div>
+      </div>
+
+      <!-- VIEW 1: DYNAMIC EQ VISUALIZER & BAND SETTINGS -->
+      <div id="viewDynamicEq" class="flex-1 flex flex-col p-4 gap-4">
+        <!-- EQ Canvas Display -->
+        <div class="relative w-full h-64 bg-slate-950 border border-slate-800/90 rounded-xl overflow-hidden shadow-inner cursor-crosshair">
+          <canvas id="eqCanvas" class="w-full h-full block"></canvas>
+        </div>
+
+        <!-- EQ Band Control Panel (Ozone Band Settings Window) -->
+        <div class="oz-panel p-3 rounded-xl grid grid-cols-4 gap-3">
+          <!-- Band 1 (Low) -->
+          <div class="bg-slate-900/80 border border-slate-800 p-2.5 rounded-lg flex flex-col justify-between">
+            <div class="flex items-center justify-between text-xs font-bold text-cyan-400">
+              <span>BAND 1 (LOW)</span>
+              <span class="text-[10px] font-mono text-slate-400">100 Hz</span>
+            </div>
+            <div class="flex items-center justify-around my-2">
+              <div class="knob-container" data-param="eqLowGain" data-min="-12" data-max="12" data-value="1.5" data-unit="dB">
+                <div class="knob-dial w-9 h-9 rounded-full bg-slate-800 border-2 border-cyan-500 relative flex items-center justify-center shadow-md">
+                  <div class="knob-pointer w-0.5 h-3 bg-cyan-400 rounded absolute top-1"></div>
+                </div>
+              </div>
+              <div class="text-center font-mono">
+                <span class="knob-val text-xs text-slate-200 font-bold">+1.5 dB</span>
+              </div>
+            </div>
+            <div class="text-[9px] text-slate-500 font-mono text-center">Shelf Filter</div>
+          </div>
+
+          <!-- Band 2 (Mid Low) -->
+          <div class="bg-slate-900/80 border border-slate-800 p-2.5 rounded-lg flex flex-col justify-between">
+            <div class="flex items-center justify-between text-xs font-bold text-amber-400">
+              <span>BAND 2 (MID LOW)</span>
+              <span class="text-[10px] font-mono text-slate-400">822 Hz</span>
+            </div>
+            <div class="flex items-center justify-around my-2">
+              <div class="knob-container" data-param="eqMid1Gain" data-min="-12" data-max="12" data-value="-1.0" data-unit="dB">
+                <div class="knob-dial w-9 h-9 rounded-full bg-slate-800 border-2 border-amber-500 relative flex items-center justify-center shadow-md">
+                  <div class="knob-pointer w-0.5 h-3 bg-amber-400 rounded absolute top-1"></div>
+                </div>
+              </div>
+              <div class="text-center font-mono">
+                <span class="knob-val text-xs text-slate-200 font-bold">-1.0 dB</span>
+              </div>
+            </div>
+            <div class="text-[9px] text-slate-500 font-mono text-center">Dynamic Bell (Q: 0.7)</div>
+          </div>
+
+          <!-- Band 3 (Mid High) -->
+          <div class="bg-slate-900/80 border border-slate-800 p-2.5 rounded-lg flex flex-col justify-between">
+            <div class="flex items-center justify-between text-xs font-bold text-purple-400">
+              <span>BAND 3 (MID HIGH)</span>
+              <span class="text-[10px] font-mono text-slate-400">3.2 kHz</span>
+            </div>
+            <div class="flex items-center justify-around my-2">
+              <div class="knob-container" data-param="eqMid2Gain" data-min="-12" data-max="12" data-value="2.0" data-unit="dB">
+                <div class="knob-dial w-9 h-9 rounded-full bg-slate-800 border-2 border-purple-500 relative flex items-center justify-center shadow-md">
+                  <div class="knob-pointer w-0.5 h-3 bg-purple-400 rounded absolute top-1"></div>
+                </div>
+              </div>
+              <div class="text-center font-mono">
+                <span class="knob-val text-xs text-slate-200 font-bold">+2.0 dB</span>
+              </div>
+            </div>
+            <div class="text-[9px] text-slate-500 font-mono text-center">Dynamic Bell (Q: 1.2)</div>
+          </div>
+
+          <!-- Band 4 (High) -->
+          <div class="bg-slate-900/80 border border-slate-800 p-2.5 rounded-lg flex flex-col justify-between">
+            <div class="flex items-center justify-between text-xs font-bold text-emerald-400">
+              <span>BAND 4 (HIGH)</span>
+              <span class="text-[10px] font-mono text-slate-400">10 kHz</span>
+            </div>
+            <div class="flex items-center justify-around my-2">
+              <div class="knob-container" data-param="eqHighGain" data-min="-12" data-max="12" data-value="1.8" data-unit="dB">
+                <div class="knob-dial w-9 h-9 rounded-full bg-slate-800 border-2 border-emerald-500 relative flex items-center justify-center shadow-md">
+                  <div class="knob-pointer w-0.5 h-3 bg-emerald-400 rounded absolute top-1"></div>
+                </div>
+              </div>
+              <div class="text-center font-mono">
+                <span class="knob-val text-xs text-slate-200 font-bold">+1.8 dB</span>
+              </div>
+            </div>
+            <div class="text-[9px] text-slate-500 font-mono text-center">High Shelf</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- VIEW 2: STEREO IMAGER VISUALIZER & CONTROLS (HIDDEN BY DEFAULT) -->
+      <div id="viewImager" class="flex-1 flex flex-col p-4 gap-4 hidden">
+        <div class="grid grid-cols-12 gap-4 flex-1">
+          <!-- Polar Vectorscope Canvas (8 Cols) -->
+          <div class="col-span-8 bg-slate-950 border border-slate-800/90 rounded-xl p-3 flex flex-col relative shadow-inner">
+            <span class="text-xs font-bold text-cyan-400 uppercase font-mono mb-2">
+              <i class="fa-solid fa-circle-nodes"></i> Polar Vectorscope & Correlation Meter
+            </span>
+            <div class="flex-1 relative w-full h-56 flex items-center justify-center">
+              <canvas id="imagerCanvas" class="w-full h-full block"></canvas>
+            </div>
+          </div>
+
+          <!-- Band Width Controls (4 Cols) -->
+          <div class="col-span-4 oz-panel p-3 rounded-xl flex flex-col justify-between">
+            <span class="text-xs font-bold text-slate-300 uppercase font-mono">4-Band Stereo Width</span>
+            
+            <div class="space-y-3 my-auto">
+              <div>
+                <div class="flex justify-between text-[11px] font-mono mb-1"><span class="text-cyan-400 font-bold">Band 1 (0-100Hz)</span><span id="w1Val">0%</span></div>
+                <input id="w1Slider" type="range" min="-100" max="100" value="0" class="w-full accent-cyan-500 h-1 cursor-pointer">
+              </div>
+              <div>
+                <div class="flex justify-between text-[11px] font-mono mb-1"><span class="text-amber-400 font-bold">Band 2 (100-1kHz)</span><span id="w2Val">+15%</span></div>
+                <input id="w2Slider" type="range" min="-100" max="100" value="15" class="w-full accent-amber-500 h-1 cursor-pointer">
+              </div>
+              <div>
+                <div class="flex justify-between text-[11px] font-mono mb-1"><span class="text-purple-400 font-bold">Band 3 (1k-6kHz)</span><span id="w3Val">+35%</span></div>
+                <input id="w3Slider" type="range" min="-100" max="100" value="35" class="w-full accent-purple-500 h-1 cursor-pointer">
+              </div>
+              <div>
+                <div class="flex justify-between text-[11px] font-mono mb-1"><span class="text-emerald-400 font-bold">Band 4 (6k-20kHz)</span><span id="w4Val">+50%</span></div>
+                <input id="w4Slider" type="range" min="-100" max="100" value="50" class="w-full accent-emerald-500 h-1 cursor-pointer">
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <!-- VIEW 3: MAXIMIZER / LIMITER VISUALIZER & CONTROLS (HIDDEN BY DEFAULT) -->
+      <div id="viewMaximizer" class="flex-1 flex flex-col p-4 gap-4 hidden">
+        <div class="oz-panel p-4 rounded-xl flex-1 grid grid-cols-12 gap-6 items-center">
+          
+          <!-- Left Gain & Output Level Panel -->
+          <div class="col-span-4 flex flex-col items-center justify-center border-r border-slate-800 pr-4">
+            <span class="text-xs font-bold text-slate-400 uppercase font-mono mb-3">Maximizer Gain Boost</span>
+            
+            <div class="knob-container my-2" data-param="maxGain" data-min="0" data-max="12" data-value="5.4" data-unit="dB">
+              <div class="knob-dial w-24 h-24 rounded-full bg-slate-900 border-4 border-cyan-500 relative flex items-center justify-center shadow-2xl">
+                <div class="knob-pointer w-1 h-8 bg-cyan-400 rounded absolute top-2"></div>
+                <span class="knob-val text-sm font-bold font-mono text-cyan-300 z-10">+5.4 dB</span>
+              </div>
+            </div>
+
+            <div class="w-full mt-4 bg-slate-950 p-2 rounded-lg border border-slate-800 text-xs font-mono flex justify-between items-center">
+              <span class="text-slate-400">Ceiling Level:</span>
+              <span class="text-cyan-400 font-bold">-0.10 dB</span>
+            </div>
+          </div>
+
+          <!-- Center Upward Comp & Soft Clip Controls -->
+          <div class="col-span-8 grid grid-cols-3 gap-4">
+            <div class="bg-slate-950 p-3 border border-slate-800 rounded-xl flex flex-col items-center">
+              <span class="text-[10px] font-bold text-slate-400 font-mono mb-2">UPWARD COMPRESS</span>
+              <div class="knob-container" data-param="maxUpward" data-min="0" data-max="10" data-value="2.0" data-unit="dB">
+                <div class="knob-dial w-12 h-12 rounded-full bg-slate-800 border-2 border-cyan-500 relative flex items-center justify-center">
+                  <div class="knob-pointer w-0.5 h-4 bg-cyan-400 rounded absolute top-1"></div>
+                </div>
+              </div>
+              <span class="knob-val text-xs font-mono text-slate-200 mt-2">+2.0 dB</span>
+            </div>
+
+            <div class="bg-slate-950 p-3 border border-slate-800 rounded-xl flex flex-col items-center">
+              <span class="text-[10px] font-bold text-slate-400 font-mono mb-2">SOFT CLIPPER</span>
+              <div class="knob-container" data-param="maxSoftClip" data-min="0" data-max="100" data-value="15" data-unit="%">
+                <div class="knob-dial w-12 h-12 rounded-full bg-slate-800 border-2 border-amber-500 relative flex items-center justify-center">
+                  <div class="knob-pointer w-0.5 h-4 bg-amber-400 rounded absolute top-1"></div>
+                </div>
+              </div>
+              <span class="knob-val text-xs font-mono text-slate-200 mt-2">15%</span>
+            </div>
+
+            <div class="bg-slate-950 p-3 border border-slate-800 rounded-xl flex flex-col items-center">
+              <span class="text-[10px] font-bold text-slate-400 font-mono mb-2">TRANSIENT EMPHASIS</span>
+              <div class="knob-container" data-param="maxTransient" data-min="0" data-max="100" data-value="25" data-unit="%">
+                <div class="knob-dial w-12 h-12 rounded-full bg-slate-800 border-2 border-emerald-500 relative flex items-center justify-center">
+                  <div class="knob-pointer w-0.5 h-4 bg-emerald-400 rounded absolute top-1"></div>
+                </div>
+              </div>
+              <span class="knob-val text-xs font-mono text-slate-200 mt-2">25%</span>
+            </div>
+          </div>
+
+        </div>
+      </div>
+
+    </div>
+
+    <!-- RIGHT SIDEBAR: MASTER INPUT / OUTPUT STEREO METER TOWER -->
+    <div class="w-64 bg-slate-900 border-l border-slate-800/80 p-3 flex flex-col justify-between shadow-2xl font-mono text-xs z-20">
+      <div class="flex items-center justify-between border-b border-slate-800 pb-2 mb-2">
+        <span class="text-xs font-bold text-white tracking-wider uppercase flex items-center gap-1.5">
+          <i class="fa-solid fa-sliders text-cyan-400"></i> I/O METERS
+        </span>
+        <span class="text-[9px] bg-cyan-950 border border-cyan-800 text-cyan-300 px-1 py-0.5 rounded">TRUE PEAK</span>
+      </div>
+
+      <!-- Peak / RMS Numeric Display -->
+      <div class="grid grid-cols-2 gap-2 text-[10px] text-center mb-2">
+        <div class="bg-slate-950 border border-slate-800/80 p-1.5 rounded">
+          <div class="text-slate-500 font-bold">IN PEAK</div>
+          <div id="inPeakText" class="text-cyan-400 font-bold font-mono">-14.2 dB</div>
+        </div>
+        <div class="bg-slate-950 border border-slate-800/80 p-1.5 rounded">
+          <div class="text-slate-500 font-bold">OUT PEAK</div>
+          <div id="outPeakText" class="text-emerald-400 font-bold font-mono">-0.1 dB</div>
+        </div>
+      </div>
+
+      <!-- Level Meters Graphic Container -->
+      <div class="flex-1 bg-slate-950 border border-slate-800/90 rounded-xl p-2 flex justify-around relative overflow-hidden my-1">
+        <!-- Input Meters (L/R) -->
+        <div class="flex flex-col items-center h-full">
+          <span class="text-[9px] text-slate-500 mb-1">IN</span>
+          <div class="flex-1 w-5 bg-slate-900 border border-slate-800 rounded relative overflow-hidden flex items-end">
+            <canvas id="inMeterCanvas" class="w-full h-full block"></canvas>
+          </div>
+        </div>
+
+        <!-- Output Meters (L/R) -->
+        <div class="flex flex-col items-center h-full">
+          <span class="text-[9px] text-slate-500 mb-1">OUT</span>
+          <div class="flex-1 w-6 bg-slate-900 border border-slate-800 rounded relative overflow-hidden flex items-end">
+            <canvas id="outMeterCanvas" class="w-full h-full block"></canvas>
+          </div>
+        </div>
+      </div>
+
+      <!-- Global Utility Buttons (Ozone Right Side Action Bar) -->
+      <div class="grid grid-cols-2 gap-1.5 mt-2">
+        <button id="masterBypassBtn" class="bg-slate-800 hover:bg-slate-700 text-slate-200 py-1.5 rounded text-[10px] font-bold border border-slate-700 transition-colors">
+          Bypass
+        </button>
+        <button class="bg-slate-800 hover:bg-slate-700 text-slate-200 py-1.5 rounded text-[10px] font-bold border border-slate-700 transition-colors">
+          Gain Match
+        </button>
+        <button class="bg-slate-800 hover:bg-slate-700 text-slate-300 py-1.5 rounded text-[10px] font-sans border border-slate-700">
+          Codec
+        </button>
+        <button class="bg-slate-800 hover:bg-slate-700 text-slate-300 py-1.5 rounded text-[10px] font-sans border border-slate-700">
+          Dither
+        </button>
+      </div>
+    </div>
+
+  </main>
+
+  <!-- JAVASCRIPT: WEB AUDIO DSP GRAPH & OZONE STUDIO LOGIC -->
+  <script>
+    // State Store for Ozone Parameters
+    const ozState = {
+      isBypassed: false,
+      activeModule: 'eq', // 'eq', 'imager', 'maximizer'
+      
+      // Module Actives
+      eqActive: true,
+      imagerActive: true,
+      maximizerActive: true,
+
+      // EQ Parameters
+      eqLowGain: 1.5,
+      eqMid1Gain: -1.0,
+      eqMid2Gain: 2.0,
+      eqHighGain: 1.8,
+
+      // Imager Band Widths
+      w1: 0,
+      w2: 15,
+      w3: 35,
+      w4: 50,
+
+      // Maximizer Parameters
+      maxGain: 5.4,
+      maxUpward: 2.0,
+      maxSoftClip: 15,
+      maxTransient: 25
+    };
+
+    // Web Audio Node Graph References
+    let audioCtx = null;
+    let sourceNode = null;
+    let inputAnalyser = null;
+    let eqLowFilter = null;
+    let eqMid1Filter = null;
+    let eqMid2Filter = null;
+    let eqHighFilter = null;
+    let maximizerBoostGain = null;
+    let maximizerCompressor = null;
+    let outputAnalyser = null;
+    let isPlaying = false;
+
+    // Web Audio Initialization
+    function initOzoneAudioEngine() {
+      if (audioCtx) return;
+
+      const AudioCtxClass = window.AudioContext || window.webkitAudioContext;
+      audioCtx = new AudioCtxClass();
+
+      // Input Analyser
+      inputAnalyser = audioCtx.createAnalyser();
+      inputAnalyser.fftSize = 2048;
+
+      // Dynamic EQ Filters
+      eqLowFilter = audioCtx.createBiquadFilter();
+      eqLowFilter.type = 'lowshelf';
+      eqLowFilter.frequency.value = 100;
+
+      eqMid1Filter = audioCtx.createBiquadFilter();
+      eqMid1Filter.type = 'peaking';
+      eqMid1Filter.frequency.value = 822;
+      eqMid1Filter.Q.value = 0.7;
+
+      eqMid2Filter = audioCtx.createBiquadFilter();
+      eqMid2Filter.type = 'peaking';
+      eqMid2Filter.frequency.value = 3200;
+      eqMid2Filter.Q.value = 1.2;
+
+      eqHighFilter = audioCtx.createBiquadFilter();
+      eqHighFilter.type = 'highshelf';
+      eqHighFilter.frequency.value = 10000;
+
+      // Maximizer Boost Gain
+      maximizerBoostGain = audioCtx.createGain();
+
+      // Brickwall Limiter Compressor
+      maximizerCompressor = audioCtx.createDynamicsCompressor();
+      maximizerCompressor.threshold.value = -0.1;
+      maximizerCompressor.knee.value = 0.0;
+      maximizerCompressor.ratio.value = 20.0;
+      maximizerCompressor.attack.value = 0.001;
+      maximizerCompressor.release.value = 0.05;
+
+      // Output Analyser
+      outputAnalyser = audioCtx.createAnalyser();
+      outputAnalyser.fftSize = 2048;
+
+      // Connect Signal Chain Graph:
+      // InputAnalyser -> EQ Low -> EQ Mid1 -> EQ Mid2 -> EQ High -> BoostGain -> Compressor -> OutputAnalyser -> Destination
+      inputAnalyser.connect(eqLowFilter);
+      eqLowFilter.connect(eqMid1Filter);
+      eqMid1Filter.connect(eqMid2Filter);
+      eqMid2Filter.connect(eqHighFilter);
+      eqHighFilter.connect(maximizerBoostGain);
+      maximizerBoostGain.connect(maximizerCompressor);
+      maximizerCompressor.connect(outputAnalyser);
+      outputAnalyser.connect(audioCtx.destination);
+
+      updateAudioGraphValues();
+    }
+
+    function updateAudioGraphValues() {
+      if (!audioCtx) return;
+      const now = audioCtx.currentTime;
+
+      eqLowFilter.gain.setTargetAtTime(ozState.eqActive ? ozState.eqLowGain : 0, now, 0.01);
+      eqMid1Filter.gain.setTargetAtTime(ozState.eqActive ? ozState.eqMid1Gain : 0, now, 0.01);
+      eqMid2Filter.gain.setTargetAtTime(ozState.eqActive ? ozState.eqMid2Gain : 0, now, 0.01);
+      eqHighFilter.gain.setTargetAtTime(ozState.eqActive ? ozState.eqHighGain : 0, now, 0.01);
+
+      const boostLinear = ozState.maximizerActive ? Math.pow(10, ozState.maxGain / 20) : 1.0;
+      maximizerBoostGain.gain.setTargetAtTime(boostLinear, now, 0.01);
+    }
+
+    // Synthesize EDM / Pop Reference Audio Loop
+    function startAudioDemo() {
+      initOzoneAudioEngine();
+      if (audioCtx.state === 'suspended') audioCtx.resume();
+      stopAudioDemo();
+
+      const sampleRate = audioCtx.sampleRate;
+      const bufferSize = sampleRate * 4; // 4 second loop
+      const buffer = audioCtx.createBuffer(2, bufferSize, sampleRate);
+      const left = buffer.getChannelData(0);
+      const right = buffer.getChannelData(1);
+
+      for (let i = 0; i < bufferSize; i++) {
+        const t = i / sampleRate;
+        // Kick Drum
+        const kickEnv = Math.max(0, 1 - (t % 0.5) * 8);
+        const kick = Math.sin(2 * Math.PI * (55 * Math.exp(-(t % 0.5) * 18))) * kickEnv;
+
+        // Snare / Claps
+        const snareEnv = Math.max(0, 1 - ((t + 0.25) % 0.5) * 6);
+        const snare = (Math.random() * 2 - 1) * snareEnv * 0.3;
+
+        // EDM Chords (C min, Ab, Eb, Bb)
+        const synth = (Math.sin(2 * Math.PI * 261.63 * t) + Math.sin(2 * Math.PI * 311.13 * t) + Math.sin(2 * Math.PI * 392.0 * t)) * 0.12;
+
+        left[i] = kick * 0.6 + snare + synth;
+        right[i] = kick * 0.6 + snare * 0.9 + synth * 0.95;
+      }
+
+      sourceNode = audioCtx.createBufferSource();
+      sourceNode.buffer = buffer;
+      sourceNode.loop = true;
+      sourceNode.connect(inputAnalyser);
+      sourceNode.start();
+
+      isPlaying = true;
+      document.getElementById('playAudioBtn').innerHTML = '<i class="fa-solid fa-pause text-[10px]"></i> <span>Pause Reference</span>';
+    }
+
+    function stopAudioDemo() {
+      if (sourceNode) {
+        try { sourceNode.stop(); } catch(e){}
+        sourceNode.disconnect();
+        sourceNode = null;
+      }
+      isPlaying = false;
+      document.getElementById('playAudioBtn').innerHTML = '<i class="fa-solid fa-play text-[10px]"></i> <span>Play Reference Loop</span>';
+    }
+
+    // Canvas Render Loops
+    function startCanvasRenderers() {
+      const eqCanvas = document.getElementById('eqCanvas');
+      const imagerCanvas = document.getElementById('imagerCanvas');
+      const inMeterCanvas = document.getElementById('inMeterCanvas');
+      const outMeterCanvas = document.getElementById('outMeterCanvas');
+
+      const eqCtx = eqCanvas.getContext('2d');
+      const imagerCtx = imagerCanvas.getContext('2d');
+      const inCtx = inMeterCanvas.getContext('2d');
+      const outCtx = outMeterCanvas.getContext('2d');
+
+      function resizeAll() {
+        eqCanvas.width = eqCanvas.clientWidth;
+        eqCanvas.height = eqCanvas.clientHeight;
+        imagerCanvas.width = imagerCanvas.clientWidth;
+        imagerCanvas.height = imagerCanvas.clientHeight;
+        inMeterCanvas.width = inMeterCanvas.clientWidth;
+        inMeterCanvas.height = inMeterCanvas.clientHeight;
+        outMeterCanvas.width = outMeterCanvas.clientWidth;
+        outMeterCanvas.height = outMeterCanvas.clientHeight;
+      }
+      resizeAll();
+      window.addEventListener('resize', resizeAll);
+
+      const fftData = new Uint8Array(1024);
+
+      function renderFrame() {
+        requestAnimationFrame(renderFrame);
+
+        // -------------------------------------------------------------
+        // 1. RENDER DYNAMIC EQ & SPECTRUM
+        // -------------------------------------------------------------
+        const w = eqCanvas.width;
+        const h = eqCanvas.height;
+        eqCtx.clearRect(0, 0, w, h);
+
+        // Draw Ozone-style Frequency Grid Lines
+        eqCtx.strokeStyle = 'rgba(51, 65, 85, 0.3)';
+        eqCtx.lineWidth = 1;
+        eqCtx.font = '9px JetBrains Mono';
+        eqCtx.fillStyle = '#475569';
+
+        const freqs = [20, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000];
+        freqs.forEach(f => {
+          const x = (Math.log10(f / 20) / Math.log10(20000 / 20)) * w;
+          eqCtx.beginPath();
+          eqCtx.moveTo(x, 0);
+          eqCtx.lineTo(x, h);
+          eqCtx.stroke();
+          if (f >= 1000) eqCtx.fillText(`${f/1000}k`, x + 3, h - 6);
+          else eqCtx.fillText(`${f}`, x + 3, h - 6);
+        });
+
+        // Draw FFT Spectrum Fill
+        if (outputAnalyser && isPlaying) {
+          outputAnalyser.getByteFrequencyData(fftData);
+          eqCtx.fillStyle = 'rgba(56, 189, 248, 0.15)';
+          const barWidth = w / 128;
+          for (let i = 0; i < 128; i++) {
+            const val = fftData[i * 4] / 255;
+            const barHeight = val * h;
+            eqCtx.fillRect(i * barWidth, h - barHeight, barWidth - 1, barHeight);
+          }
+        }
+
+        // Draw Composite EQ Response Curve
+        eqCtx.strokeStyle = '#38bdf8';
+        eqCtx.lineWidth = 2.5;
+        eqCtx.beginPath();
+
+        for (let x = 0; x < w; x++) {
+          const freq = 20 * Math.pow(20000 / 20, x / w);
+          let gainDb = 0;
+
+          if (ozState.eqActive) {
+            // Low Shelf
+            gainDb += ozState.eqLowGain / (1 + Math.pow(freq / 100, 2));
+            // Mid 1 Bell
+            gainDb += ozState.eqMid1Gain * Math.exp(-Math.pow(Math.log(freq / 822), 2) * 2);
+            // Mid 2 Bell
+            gainDb += ozState.eqMid2Gain * Math.exp(-Math.pow(Math.log(freq / 3200), 2) * 2);
+            // High Shelf
+            gainDb += ozState.eqHighGain / (1 + Math.pow(10000 / freq, 2));
+          }
+
+          const y = h / 2 - (gainDb / 18) * (h / 2);
+          if (x === 0) eqCtx.moveTo(x, y);
+          else eqCtx.lineTo(x, y);
+        }
+        eqCtx.stroke();
+
+        // -------------------------------------------------------------
+        // 2. RENDER IMAGER POLAR VECTORSCOPE
+        // -------------------------------------------------------------
+        const iw = imagerCanvas.width;
+        const ih = imagerCanvas.height;
+        imagerCtx.clearRect(0, 0, iw, ih);
+
+        // Scope Polar Circle Guides
+        imagerCtx.strokeStyle = 'rgba(51, 65, 85, 0.4)';
+        imagerCtx.lineWidth = 1;
+        imagerCtx.beginPath();
+        imagerCtx.arc(iw / 2, ih / 2, ih / 3, 0, Math.PI * 2);
+        imagerCtx.stroke();
+
+        // Scope Dynamic Stereo Dots Animation
+        if (isPlaying) {
+          imagerCtx.fillStyle = '#38bdf8';
+          for (let i = 0; i < 40; i++) {
+            const angle = (Math.random() - 0.5) * (Math.PI / 2) + (-Math.PI / 2);
+            const radius = (Math.random() * (ih / 3.2));
+            const x = iw / 2 + Math.cos(angle) * radius * (1 + ozState.w3 / 100);
+            const y = ih / 2 + Math.sin(angle) * radius;
+            imagerCtx.fillRect(x, y, 2, 2);
+          }
+        }
+
+        // -------------------------------------------------------------
+        // 3. RENDER I/O STEREO METER TOWERS
+        // -------------------------------------------------------------
+        renderMeterBar(inCtx, inMeterCanvas.width, inMeterCanvas.height, isPlaying ? 0.55 : 0.05, 'inPeakText');
+        renderMeterBar(outCtx, outMeterCanvas.width, outMeterCanvas.height, isPlaying ? 0.85 : 0.05, 'outPeakText');
+      }
+
+      function renderMeterBar(ctx, w, h, level, textId) {
+        ctx.clearRect(0, 0, w, h);
+        const barH = level * h;
+
+        const grad = ctx.createLinearGradient(0, h, 0, 0);
+        grad.addColorStop(0, '#38bdf8');
+        grad.addColorStop(0.7, '#f59e0b');
+        grad.addColorStop(1, '#ef4444');
+
+        ctx.fillStyle = grad;
+        ctx.fillRect(2, h - barH, w - 4, barH);
+
+        const dbVal = (20 * Math.log10(level)).toFixed(1);
+        document.getElementById(textId).innerText = isPlaying ? `${dbVal} dB` : '-inf dB';
+      }
+
+      renderFrame();
+    }
+
+    // Rotary Knob Drag Interactions
+    function setupKnobs() {
+      document.querySelectorAll('.knob-container').forEach(knob => {
+        let isDragging = false;
+        let startY = 0;
+        let startVal = parseFloat(knob.dataset.value);
+
+        const param = knob.dataset.param;
+        const min = parseFloat(knob.dataset.min);
+        const max = parseFloat(knob.dataset.max);
+        const unit = knob.dataset.unit || '';
+
+        const dial = knob.querySelector('.knob-dial');
+        const valText = knob.parentElement.querySelector('.knob-val');
+
+        function updateUI(val) {
+          const pct = (val - min) / (max - min);
+          const angle = -135 + pct * 270;
+          dial.style.transform = `rotate(${angle}deg)`;
+
+          if (valText) {
+            valText.innerText = `${val > 0 && unit==='dB' ? '+' : ''}${val.toFixed(1)} ${unit}`;
+          }
+
+          ozState[param] = val;
+          updateAudioGraphValues();
+        }
+
+        updateUI(startVal);
+
+        knob.addEventListener('pointerdown', e => {
+          isDragging = true;
+          startY = e.clientY;
+          startVal = ozState[param];
+          knob.setPointerCapture(e.pointerId);
+        });
+
+        knob.addEventListener('pointermove', e => {
+          if (!isDragging) return;
+          const deltaY = startY - e.clientY;
+          const range = max - min;
+          let newVal = startVal + (deltaY / 100) * range;
+          newVal = Math.min(max, Math.max(min, newVal));
+          updateUI(newVal);
+        });
+
+        knob.addEventListener('pointerup', e => {
+          isDragging = false;
+          knob.releasePointerCapture(e.pointerId);
+        });
+      });
+    }
+
+    // Module Switcher Navigation Logic
+    function setupModuleNavigation() {
+      const cardEq = document.getElementById('cardDynamicEq');
+      const cardImager = document.getElementById('cardImager');
+      const cardMaximizer = document.getElementById('cardMaximizer');
+
+      const viewEq = document.getElementById('viewDynamicEq');
+      const viewImager = document.getElementById('viewImager');
+      const viewMaximizer = document.getElementById('viewMaximizer');
+
+      function switchModule(activeCard, activeView, name) {
+        [cardEq, cardImager, cardMaximizer].forEach(c => c.classList.remove('oz-card-active'));
+        [viewEq, viewImager, viewMaximizer].forEach(v => v.classList.add('hidden'));
+
+        activeCard.classList.add('oz-card-active');
+        activeView.classList.remove('hidden');
+        ozState.activeModule = name;
+      }
+
+      cardEq.addEventListener('click', () => switchModule(cardEq, viewEq, 'eq'));
+      cardImager.addEventListener('click', () => switchModule(cardImager, viewImager, 'imager'));
+      cardMaximizer.addEventListener('click', () => switchModule(cardMaximizer, viewMaximizer, 'maximizer'));
+    }
+
+    // DOM Load Init
+    window.addEventListener('load', () => {
+      document.getElementById('playAudioBtn').addEventListener('click', () => {
+        if (isPlaying) stopAudioDemo();
+        else startAudioDemo();
+      });
+
+      document.getElementById('stopAudioBtn').addEventListener('click', stopAudioDemo);
+
+      setupKnobs();
+      setupModuleNavigation();
+      startCanvasRenderers();
+    });
+  </script>
+</body>
+</html>
+
+```

md/46_MAIN_OUT_SLIDER.md

@@ -0,0 +1,72 @@
+# IMPACT OF MAIN OUT VOLUME SLIDER IN THE AUDIO PROCESSING PIPELINE
+
+In Web DAW and Mastering Suite audio architectures (powered by the Web Audio API), the MAIN OUT Volume Slider serves as the final amplification control node (**Post-Processing Master Gain Node**).
+
+Below is a detailed breakdown of how the MAIN OUT slider impacts the audio signal processing chain:
+
+---
+
+## 1. Signal Graph Position
+
+The MAIN OUT Volume Slider controls a `GainNode` located at the very end of the processing chain (**Post-FX Stage**), directly preceding hardware output delivery (`AudioContext.destination` / Speakers / Headphones):
+
+```text
+[ Input Analyser ]
+       │
+       ▼
+[ Processing Chain ] (Dynamic EQ ➔ Stereo Imager ➔ Maximizer / Limiter)
+       │
+       ▼
+[ MAIN OUT Volume Slider (Gain Node) ] ◄── (dB Adjustment Slider)
+       │
+       ▼
+[ Output Analyser / Peak Meter ]
+       │
+       ▼
+[ AudioContext.destination ] (Hardware Speakers / DAC)
+
+```
+
+---
+
+## 2. Specific Impacts on the Audio Stream
+
+### 1. Dynamics & Character Unchanged
+
+Because it is placed after the processing modules (Compressor, Dynamic EQ, Maximizer/Limiter), increasing or decreasing the MAIN OUT level **does NOT** alter compression behavior, harmonic saturation, or the ceiling/threshold point of the Brickwall Limiter.
+
+The audio retains $100\%$ of its tonal color, frequency balance, and dynamic range ratio processed by the Master FX chain.
+
+### 2. Linear Amplitude Scaling
+
+The slider converts decibel values ($\text{dB}$) into a linear gain factor $G$ using the standard formula:
+
+$$G = 10^{\frac{\text{dB}}{20}}$$
+
+All PCM Float32 audio samples ($[-1.0, 1.0]$) passing through the node are multiplied directly by this factor $G$:
+
+$$S_{\text{out}}(t) = S_{\text{processed}}(t) \times G$$
+
+### 3. Impact on Hardware Output & Clipping
+
+* **Decreasing the Slider ($< 0\text{ dB}$):** Reduces the waveform amplitude, allowing users to lower the monitoring volume without affecting the underlying Master processing.
+* **Increasing the Slider ($> 0\text{ dB}$):** Increases signal amplitude. If the scaled amplitude exceeds $1.0$ ($0\text{ dBFS}$), the digital-to-analog converter (DAC) will suffer from hardware clipping and distortion—even if the preceding Maximizer successfully capped true peaks.
+
+### 4. Impact on Output Metering (Post-Fader Metering)
+
+When set to Post-Fader mode, output Peak/RMS/LUFS meters accurately reflect signal levels after multiplication by the MAIN OUT Gain factor. This ensures operators monitor the actual signal level going to speakers or export files.
+
+### 5. Impact on WAV Bounce / Export
+
+During final mix export (**Master WAV Export**), the MAIN OUT Slider value scales the entire final PCM Audio Buffer. Consequently, this slider dictates the absolute volume level of the rendered output WAV file.
+
+---
+
+## 3. Comparison Matrix: MAXIMIZER GAIN vs. MAIN OUT SLIDER
+
+| Parameter / Criteria | Maximizer Boost Gain | MAIN OUT Volume Slider |
+| --- | --- | --- |
+| **Signal Chain Location** | Inside FX Chain (Pre-Limiter) | After FX Chain (Post-Limiter) |
+| **Dynamics Impact** | Alters LUFS, drives signal into Ceiling, increases compression density. | Does NOT alter dynamics; purely scales master output volume. |
+| **Clipping Risk** | **No** (Controlled/limited by the Brickwall Ceiling). | **Yes** (Boosting $> 0\text{ dB}$ can exceed $0\text{ dBFS}$ and clip the DAC). |
+| **Primary Purpose** | Increases perceived loudness (LUFS). | Controls monitoring volume for speakers/headphones or final export scaling. |

md/47_MASTER_STRIP_CONSOLE.md

@@ -0,0 +1,458 @@
+I have created `master_strip_gui.html` containing both the Markdown visual description and the full HTML5 implementation of the Master Strip console.
+
+### Summary of What Was Created:
+1. **Markdown Documentation Section**:
+   * **Signal Flow**: Detailing the `Source -> Main Out Slider (Gain) -> Analyser -> Destination` post-fader audio path.
+   * **Component Layout Breakdown**: Detailing the top routing header, dual stereo VU meters, narrow vertical fader, right-hand button stack, and RMS readout footer.
+2. **HTML5 Implementation**:
+   * **Dual Stereo VU Meter**: Canvas-based visualizer featuring L/R channels with dB markings on both sides (`+12` to `-54 dB`).
+   * **Post-Fader Audio Engine**: AudioContext graph with live sine/kick test generator responding dynamically to slider and mastering panel controls.
+
+``` html
+
+<!DOCTYPE html>
+<html lang="vi" class="h-full bg-slate-950 text-slate-100 select-none">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>DAW Master Strip Console</title>
+  <!-- Tailwind CSS -->
+  <script src="https://cdn.tailwindcss.com"></script>
+  <!-- Font Awesome Icons -->
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+  <!-- Fonts -->
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet">
+  
+  <style>
+    body { font-family: 'Inter', sans-serif; }
+    .font-mono { font-family: 'JetBrains Mono', monospace; }
+
+    /* REAPER Metallic Dark DAW Styling */
+    .strip-bg {
+      background: linear-gradient(180deg, #2f2f2f 0%, #222222 100%);
+      border: 1px solid #141414;
+      box-shadow: inset 1px 1px 0 rgba(255,255,255,0.08), 0 8px 24px rgba(0,0,0,0.8);
+    }
+
+    .fader-track {
+      background: #121212;
+      box-shadow: inset 1px 1px 3px rgba(0,0,0,0.9), 1px 1px 0 rgba(255,255,255,0.05);
+    }
+
+    /* DAW Metallic Button */
+    .btn-daw {
+      background: linear-gradient(180deg, #444 0%, #2a2a2a 100%);
+      border: 1px solid #1a1a1a;
+      box-shadow: inset 0 1px 0 rgba(255,255,255,0.15), 0 2px 4px rgba(0,0,0,0.5);
+      transition: all 0.1s ease;
+    }
+    .btn-daw:hover {
+      background: linear-gradient(180deg, #555 0%, #333 100%);
+    }
+    .btn-daw:active {
+      box-shadow: inset 0 2px 4px rgba(0,0,0,0.8);
+      transform: translateY(0.5px);
+    }
+
+    /* Teal Active State (FX & Power Button) */
+    .btn-teal-active {
+      background: linear-gradient(180deg, #10b981 0%, #047857 100%) !important;
+      border-color: #34d399 !important;
+      color: #ffffff !important;
+      box-shadow: 0 0 10px rgba(16, 185, 129, 0.6) !important;
+    }
+
+    /* Mute & Solo Active State */
+    .btn-mute-active {
+      background: linear-gradient(180deg, #ef4444 0%, #991b1b 100%) !important;
+      border-color: #f87171 !important;
+      color: #ffffff !important;
+      box-shadow: 0 0 8px rgba(239, 68, 68, 0.6) !important;
+    }
+
+    .btn-mono-active {
+      background: linear-gradient(180deg, #3b82f6 0%, #1e40af 100%) !important;
+      border-color: #60a5fa !important;
+      color: #ffffff !important;
+    }
+
+    /* Custom Vertical Range Fader Slider */
+    input[type=range].fader-slider {
+      appearance: none;
+      -webkit-appearance: none;
+      writing-mode: vertical-lr;
+      direction: rtl;
+      background: transparent;
+      cursor: pointer;
+    }
+    input[type=range].fader-slider::-webkit-slider-thumb {
+      -webkit-appearance: none;
+      height: 24px;
+      width: 22px;
+      background: linear-gradient(180deg, #e2e8f0 0%, #64748b 45%, #1e293b 50%, #94a3b8 100%);
+      border: 1px solid #000000;
+      border-radius: 2px;
+      box-shadow: 0 4px 8px rgba(0,0,0,0.9), inset 0 1px 1px rgba(255,255,255,0.9);
+    }
+    input[type=range].fader-slider::-moz-range-thumb {
+      height: 24px;
+      width: 22px;
+      background: linear-gradient(180deg, #e2e8f0 0%, #64748b 45%, #1e293b 50%, #94a3b8 100%);
+      border: 1px solid #000000;
+      border-radius: 2px;
+      box-shadow: 0 4px 8px rgba(0,0,0,0.9), inset 0 1px 1px rgba(255,255,255,0.9);
+    }
+  </style>
+</head>
+<body class="h-screen bg-slate-950 flex items-center justify-center p-4 overflow-hidden select-none">
+
+  <!-- DAW MASTER STRIP CONSOLE (REAPER RE-CREATION - CLEAN COMPONENT) -->
+  <div id="masterStrip" class="w-[400px] strip-bg rounded-lg p-3 flex flex-col justify-between text-slate-300 select-none shadow-2xl relative">
+    
+    <!-- 1. TOP HEADER BUTTONS -->
+    <div class="space-y-1.5 mb-2">
+      <button class="w-full bg-slate-800 hover:bg-slate-700 text-[10px] font-semibold py-1 rounded border border-slate-700 text-slate-300 tracking-tight" title="FX Name">
+        MASTERING PANEL
+      </button>
+      <div class="flex items-center justify-between bg-slate-950 border border-slate-800 rounded px-1.5 py-0.5 text-[10px] font-mono">
+        <span class="text-slate-400 truncate">Output 1 / Output 2</span>
+        <i class="fa-solid fa-circle-notch text-[9px] text-slate-500"></i>
+      </div>
+    </div>
+
+    <!-- 2. PAN KNOB & DB READOUT -->
+    <div class="flex flex-col items-center my-1.5">
+      <span id="panText" class="text-[10px] text-slate-400 font-mono mb-0.5">center</span>
+      <!-- Pan Rotary Dial -->
+      <div id="panDial" class="w-7 h-7 rounded-full bg-slate-800 border-2 border-slate-600 relative flex items-center justify-center shadow-inner cursor-pointer" title="Kéo chuột để chỉnh Pan (Left/Right)">
+        <div id="panPointer" class="w-0.5 h-2.5 bg-slate-200 rounded absolute top-0.5 transition-transform" style="transform: rotate(0deg);"></div>
+      </div>
+      <div id="dbReadoutText" class="text-xs font-bold font-mono text-slate-200 mt-1.5">0.00dB</div>
+      <div class="flex justify-between w-full text-[9px] font-mono text-slate-400 px-4 mt-0.5">
+        <span id="peakL">-inf</span>
+        <span id="peakR">-inf</span>
+      </div>
+    </div>
+
+    <!-- 3. CENTER AREA: LARGE DUAL-CHANNEL STEREO VU METER + NARROW VOLUME SLIDER + BUTTON STACK -->
+    <div class="flex-1 flex gap-2 my-2 justify-between items-stretch">
+      
+      <!-- LARGE DUAL-CHANNEL STEREO VU METER WITH DB SCALES ON BOTH SIDES -->
+      <div class="flex-1 flex items-center justify-between bg-black/80 p-1.5 rounded border border-slate-800/90 relative shadow-inner">
+        <!-- Left Channel dB Scale Markings -->
+        <div class="flex flex-col justify-between h-56 text-[8px] font-mono text-slate-400 select-none pr-1 text-right border-r border-slate-800/60">
+          <span>+12</span>
+          <span>+6</span>
+          <span>0</span>
+          <span>-6</span>
+          <span>-12</span>
+          <span>-18</span>
+          <span>-24</span>
+          <span>-30</span>
+          <span>-36</span>
+          <span>-42</span>
+          <span>-54</span>
+        </div>
+
+        <!-- Dual Stereo VU Meter Canvas (Left & Right Channels) -->
+        <div class="flex-1 h-56 relative bg-slate-950 rounded overflow-hidden mx-1.5 border border-slate-900">
+          <canvas id="vuMeterCanvas" class="w-full h-full block"></canvas>
+          <!-- L and R Labels -->
+          <div class="absolute bottom-0.5 inset-x-0 flex justify-around text-[7px] font-mono text-slate-500 font-bold pointer-events-none bg-black/60 py-0.5">
+            <span>L</span>
+            <span>R</span>
+          </div>
+        </div>
+
+        <!-- Right Channel dB Scale Markings -->
+        <div class="flex flex-col justify-between h-56 text-[8px] font-mono text-slate-400 select-none pl-1 text-left border-l border-slate-800/60">
+          <span>+12</span>
+          <span>+6</span>
+          <span>0</span>
+          <span>-6</span>
+          <span>-12</span>
+          <span>-18</span>
+          <span>-24</span>
+          <span>-30</span>
+          <span>-36</span>
+          <span>-42</span>
+          <span>-54</span>
+        </div>
+      </div>
+
+      <!-- NARROW VOLUME SLIDER TRACK WITH SIDE DB SCALE -->
+      <div class="w-16 flex items-center gap-1 bg-slate-900/60 p-1 rounded border border-slate-800">
+        <div class="flex-1 flex flex-col items-center justify-center relative fader-track rounded py-2 px-0.5 h-56">
+          <!-- Center Fader Rail Line -->
+          <div class="w-0.5 h-full bg-slate-700 absolute"></div>
+          
+          <!-- Master Fader Slider -->
+          <input id="masterFader" type="range" min="-60" max="12" step="0.5" value="0"
+                 class="fader-slider w-full h-52 z-10" title="Chỉnh Volume Master (Post-Fader Gain)">
+        </div>
+
+        <!-- Fader Side Scale Markings -->
+        <div class="flex flex-col justify-between h-52 text-[7px] font-mono text-slate-500 select-none pr-0.5">
+          <span>+12</span>
+          <span>+6</span>
+          <span>0</span>
+          <span>-6</span>
+          <span>-12</span>
+          <span>-24</span>
+          <span>-36</span>
+          <span>-54</span>
+        </div>
+      </div>
+
+      <!-- RIGHT SIDE BUTTON STACK (MONO, M, S, ROUTE, FX, POWER, TRIM, INFO) -->
+      <div class="w-8 flex flex-col justify-between gap-1 text-[10px] font-bold">
+        <button id="monoBtn" class="btn-daw h-5 rounded flex flex-col items-center justify-center text-[8px]" title="Mono Switch">
+          <i class="fa-solid fa-circle-half-stroke text-[9px]"></i>
+          <span>MONO</span>
+        </button>
+
+        <button id="muteBtn" class="btn-daw h-5 rounded text-amber-500 font-bold hover:text-amber-400" title="Mute Master Output">
+          M
+        </button>
+
+        <button id="soloBtn" class="btn-daw h-5 rounded text-yellow-400 font-bold hover:text-yellow-300" title="Solo Master">
+          S
+        </button>
+
+        <button class="btn-daw h-5 rounded text-slate-400 hover:text-slate-200" title="Route Matrix">
+          <i class="fa-solid fa-diagram-project text-[9px]"></i>
+        </button>
+
+        <!-- THE FX BUTTON (CLICK TO OPEN MASTERING PANEL) -->
+        <button id="fxBtn" class="btn-daw btn-teal-active h-6 rounded font-extrabold text-[10px] transition-all" title="Mở MASTERING PANEL để chỉnh sửa">
+          FX
+        </button>
+
+        <!-- POWER TOGGLE BUTTON (MASTERING PANEL ON/OFF) -->
+        <button id="powerBtn" class="btn-daw btn-teal-active h-6 rounded text-xs transition-all" title="Bật/Tắt MASTERING PANEL Bypass">
+          <i class="fa-solid fa-power-off"></i>
+        </button>
+
+        <button class="btn-daw h-5 rounded text-slate-400 text-[8px]" title="Trim Envelope">
+          TRIM
+        </button>
+
+        <button class="btn-daw h-5 rounded text-slate-400 text-[9px]" title="Session Info">
+          <i class="fa-solid fa-info"></i>
+        </button>
+      </div>
+
+    </div>
+
+    <!-- 4. FOOTER IDENTIFIER -->
+    <div class="mt-2 pt-1 border-t border-slate-800 flex flex-col items-center">
+      <div class="flex justify-between w-full text-[9px] font-mono mb-0.5">
+        <span class="text-emerald-400">RMS</span>
+        <span id="rmsVal" class="text-emerald-400 font-bold">-inf</span>
+      </div>
+      <div class="w-full text-center bg-black/80 py-0.5 rounded border border-slate-800 text-xs font-extrabold tracking-widest text-slate-100 uppercase">
+        MASTER
+      </div>
+    </div>
+
+  </div>
+
+  <!-- MASTERING PANEL MODAL OVERLAY (OPENED BY FX BUTTON) -->
+  <div id="masteringModal" class="fixed inset-0 bg-black/80 backdrop-blur-sm z-50 flex items-center justify-center hidden">
+    <div class="w-11/12 max-w-3xl bg-slate-900 border border-slate-700 rounded-2xl shadow-2xl p-5 space-y-4">
+      <div class="flex items-center justify-between border-b border-slate-800 pb-3">
+        <div class="flex items-center gap-2">
+          <div class="w-3 h-3 rounded-full bg-emerald-400 animate-pulse"></div>
+          <h3 class="text-sm font-bold text-white uppercase tracking-wider">OZONE STYLE MASTERING SUITE PANEL</h3>
+        </div>
+        <button id="closeModalBtn" class="w-8 h-8 rounded-lg bg-slate-800 hover:bg-slate-700 text-white flex items-center justify-center transition-colors">
+          <i class="fa-solid fa-xmark"></i>
+        </button>
+      </div>
+
+      <div class="grid grid-cols-3 gap-3">
+        <div class="bg-slate-950 p-3 rounded-xl border border-slate-800 text-center">
+          <span class="text-xs font-bold text-cyan-400 font-mono">DYNAMIC EQ</span>
+          <div class="text-[10px] text-slate-400 mt-2">4-Band Logarithmic Curve</div>
+        </div>
+        <div class="bg-slate-950 p-3 rounded-xl border border-slate-800 text-center">
+          <span class="text-xs font-bold text-amber-400 font-mono">STEREO IMAGER</span>
+          <div class="text-[10px] text-slate-400 mt-2">Polar Vectorscope Expansion</div>
+        </div>
+        <div class="bg-slate-950 p-3 rounded-xl border border-slate-800 text-center">
+          <span class="text-xs font-bold text-emerald-400 font-mono">IRC MAXIMIZER</span>
+          <div class="text-[10px] text-slate-400 mt-2">True Peak Brickwall Limiter</div>
+        </div>
+      </div>
+
+      <div class="p-3 bg-slate-950 rounded-xl border border-slate-800 text-xs font-mono text-slate-300 text-center">
+        Mastering FX Chain đang xử lý tín hiệu trước khi đi qua MAIN OUT Volume Slider.
+      </div>
+    </div>
+  </div>
+
+  <!-- JAVASCRIPT ENGINE & EVENT LISTENERS -->
+  <script>
+    // State Store
+    const masterState = {
+      volumeDb: 0.0,
+      pan: 0.0,
+      isMuted: false,
+      isMono: false,
+      isFxActive: true
+    };
+
+    // Element References
+    const masterFader = document.getElementById('masterFader');
+    const dbReadoutText = document.getElementById('dbReadoutText');
+    const peakL = document.getElementById('peakL');
+    const peakR = document.getElementById('peakR');
+    const rmsVal = document.getElementById('rmsVal');
+    const panDial = document.getElementById('panDial');
+    const panPointer = document.getElementById('panPointer');
+    const panText = document.getElementById('panText');
+    const fxBtn = document.getElementById('fxBtn');
+    const powerBtn = document.getElementById('powerBtn');
+    const muteBtn = document.getElementById('muteBtn');
+    const monoBtn = document.getElementById('monoBtn');
+    const masteringModal = document.getElementById('masteringModal');
+    const vuCanvas = document.getElementById('vuMeterCanvas');
+    const vuCtx = vuCanvas.getContext('2d');
+
+    // Linear gain conversion: G = 10^(dB / 20)
+    function updateVolumeDisplay() {
+      const db = parseFloat(masterFader.value);
+      masterState.volumeDb = db;
+      dbReadoutText.innerText = db <= -60 ? '-inf dB' : `${db > 0 ? '+' : ''}${db.toFixed(2)}dB`;
+    }
+
+    masterFader.addEventListener('input', updateVolumeDisplay);
+
+    // Rotary Pan Knob Dragging
+    let isPanDragging = false;
+    let panStartY = 0;
+    let startPanVal = 0;
+
+    panDial.addEventListener('pointerdown', (e) => {
+      isPanDragging = true;
+      panStartY = e.clientY;
+      startPanVal = masterState.pan;
+      panDial.setPointerCapture(e.pointerId);
+    });
+
+    panDial.addEventListener('pointermove', (e) => {
+      if (!isPanDragging) return;
+      const deltaY = panStartY - e.clientY;
+      let newPan = startPanVal + (deltaY / 80);
+      newPan = Math.min(1.0, Math.max(-1.0, newPan));
+
+      masterState.pan = newPan;
+      const angle = newPan * 120;
+      panPointer.style.transform = `rotate(${angle}deg)`;
+
+      if (newPan === 0) panText.innerText = 'center';
+      else if (newPan < 0) panText.innerText = `L${Math.abs(Math.round(newPan * 100))}`;
+      else panText.innerText = `R${Math.round(newPan * 100)}`;
+    });
+
+    panDial.addEventListener('pointerup', (e) => {
+      isPanDragging = false;
+      try { panDial.releasePointerCapture(e.pointerId); } catch(err){}
+    });
+
+    // Mute & Mono Buttons
+    muteBtn.addEventListener('click', () => {
+      masterState.isMuted = !masterState.isMuted;
+      muteBtn.classList.toggle('btn-mute-active', masterState.isMuted);
+    });
+
+    monoBtn.addEventListener('click', () => {
+      masterState.isMono = !masterState.isMono;
+      monoBtn.classList.toggle('btn-mono-active', masterState.isMono);
+    });
+
+    // Modal Trigger Buttons
+    fxBtn.addEventListener('click', () => {
+      masteringModal.classList.remove('hidden');
+    });
+
+    document.getElementById('closeModalBtn').addEventListener('click', () => {
+      masteringModal.classList.add('hidden');
+    });
+
+    powerBtn.addEventListener('click', () => {
+      masterState.isFxActive = !masterState.isFxActive;
+      powerBtn.classList.toggle('btn-teal-active', masterState.isFxActive);
+      fxBtn.classList.toggle('btn-teal-active', masterState.isFxActive);
+    });
+
+    // Dynamic Stereo VU Meter Renderer (Post-Fader Level Simulation)
+    function renderVuMeter() {
+      requestAnimationFrame(renderVuMeter);
+
+      vuCanvas.width = vuCanvas.clientWidth;
+      vuCanvas.height = vuCanvas.clientHeight;
+
+      const w = vuCanvas.width;
+      const h = vuCanvas.height;
+
+      vuCtx.clearRect(0, 0, w, h);
+
+      let levelL = 0;
+      let levelR = 0;
+
+      if (!masterState.isMuted) {
+        const db = masterState.volumeDb;
+        const linearGain = db <= -60 ? 0 : Math.pow(10, db / 20);
+        
+        // Post-Fader Dynamic Level simulation
+        const baseSignal = 0.5 * linearGain;
+        if (baseSignal > 0) {
+          levelL = Math.min(1.0, Math.max(0, baseSignal * (0.9 + Math.random() * 0.18)));
+          levelR = Math.min(1.0, Math.max(0, baseSignal * (0.88 + Math.random() * 0.22)));
+          if (masterState.isMono) {
+            const monoLevel = (levelL + levelR) / 2;
+            levelL = monoLevel;
+            levelR = monoLevel;
+          }
+        }
+      }
+
+      // Draw 2 Stereo Channel Bars (Left and Right)
+      const padding = 4;
+      const gap = 4;
+      const barW = Math.max(4, (w - padding * 2 - gap) / 2);
+
+      // Color Gradient: Green -> Amber -> Red
+      const grad = vuCtx.createLinearGradient(0, h, 0, 0);
+      grad.addColorStop(0, '#10b981');
+      grad.addColorStop(0.7, '#f59e0b');
+      grad.addColorStop(0.95, '#ef4444');
+
+      vuCtx.fillStyle = grad;
+
+      // Left Channel Bar
+      const barHL = levelL * h;
+      vuCtx.fillRect(padding, h - barHL, barW, barHL);
+
+      // Right Channel Bar
+      const barHR = levelR * h;
+      vuCtx.fillRect(padding + barW + gap, h - barHR, barW, barHR);
+
+      // Numeric Peak & RMS dB Readouts
+      const dbValL = levelL > 0 ? (20 * Math.log10(levelL)).toFixed(1) : '-inf';
+      const dbValR = levelR > 0 ? (20 * Math.log10(levelR)).toFixed(1) : '-inf';
+      
+      peakL.innerText = levelL > 0 ? `${dbValL}dB` : '-inf';
+      peakR.innerText = levelR > 0 ? `${dbValR}dB` : '-inf';
+      
+      const maxLevel = Math.max(levelL, levelR);
+      rmsVal.innerText = maxLevel > 0 ? `${(20 * Math.log10(maxLevel) - 3.2).toFixed(1)} dB` : '-inf';
+    }
+
+    renderVuMeter();
+  </script>
+</body>
+</html>
+
+```

md/48_TRACK_STRIP_COMPONENT.md

@@ -0,0 +1,461 @@
+# TECHNICAL SPECIFICATION & VISUAL DISPLAY GUIDE: TRACK CHANNEL STRIP
+
+---
+
+## 1. Visual Geometry & Layout Description
+
+The Track Channel Strip is built as a vertical, compact metal unit (*Fixed Compact Unit*) modeled after professional DAWs like REAPER with fixed dimensions of **$145\text{px} \times 370\text{px}$**.
+
+The user interface consists of 6 functional zones arranged vertically from top to bottom:
+
+```text
++-------------------------------------------------------------+
+| 1. TOP TRACK COLOR ACCENT BAR (Height: 6px)                 |
++-------------------------------------------------------------+
+| 2. PAN ROTARY DIAL AREA (Height: 46px)                      |
+|    - Rotary Knob Dial (Left / Right Panning)                |
+|    - Text Readout: "center", "L50", "R100"                  |
++-------------------------------------------------------------+
+| 3. CENTER DUAL-COLUMN AREA (Height: 210px)                  |
+|    +--------------------------+ +-------------------------+ |
+|    | Peak dB Value (-inf/dB)  | | [M] Mute Switch         | |
+|    | +----------------------+ | | [S] Solo Switch         | |
+|    | | Rail Track (160px)   | | | [Routing Matrix]        | |
+|    | | - Metal Fader Cap    | | | [FX Chain]              | |
+|    | +----------------------+ | | [⏻] FX Power Toggle     | |
+|    | +----------------------+ | | [Automation Envelopes]  | |
+|    | | LED Peak VU Canvas   | | | [Ø] Phase Invert (180°) | |
+|    | +----------------------+ | +-------------------------+ |
+|    +--------------------------+                             |
++-------------------------------------------------------------+
+| 4. RECORD ARM BUTTON ROW (Height: 28px)                     |
+|    - Input Monitor Icon + Glowing Red ARM Button (🔴)       |
++-------------------------------------------------------------+
+| 5. TRACK NAME IDENTIFIER (Height: 26px)                     |
+|    - Dark Box with Track Name Display ("PIANO")             |
++-------------------------------------------------------------+
+| 6. TRACK COLOR FOOTER BAR (Height: 22px)                    |
+|    - Accent Background with Track Index Number ("1")        |
++-------------------------------------------------------------+
+
+```
+
+---
+
+## 2. Audio Processing Graph & Wiring (Web Audio API)
+
+Audio signals passing through the Track Channel Strip follow a serial processing chain (*Post-FX Signal Path*):
+
+$$\text{Input Source} \xrightarrow{\quad} \text{Phase Invert ($\text{\O}$)} \xrightarrow{\quad} \text{Track FX Chain} \xrightarrow{\quad} \text{Mute / Solo Switch} \xrightarrow{\quad} \text{Volume Fader (Gain)} \xrightarrow{\quad} \text{Stereo Panner} \xrightarrow{\quad} \text{Analyser (VU Meter)} \xrightarrow{\quad} \text{Master Bus}$$
+
+* **Phase Invert ($\text{\O}$):** Inverts the signal phase by $180^\circ$ ($G = -1$) to resolve phase cancellation issues between multiple microphone inputs.
+* **Track FX Chain:** Dedicated track insertion effects (Dynamic EQ, Reverb, Delay).
+* **Mute / Solo Logic:**
+* **Mute [M]:** Sets Linear Gain = $0.0$.
+* **Solo [S]:** Silences all other non-soloed tracks across the session.
+
+
+* **Volume Fader Scaling:** Converts decibels ($\text{dB}$) from the fader position into a linear gain factor $G$:
+
+$$G = 10^{\frac{\text{dB}}{20}}$$
+
+
+
+*(Control range: $-60\text{ dB}$ to $+12\text{ dB}$)*.
+* **Stereo Panner:** Adjusts spatial positioning across the stereo field from Left ($-1.0$) to Right ($+1.0$).
+* **Peak VU Metering:** An `AnalyserNode` extracts real-time amplitude data to render a dynamic LED meter (Green $\to$ Yellow $\to$ Red).
+
+---
+
+## 3. Practical Track Channel Applications
+
+* **Mixer Dock Rendering:** Iterates and renders a strip for each item in `session.tracks` along the docked Mixer Console at the bottom of the screen.
+* **Color Accent Synchronization:** Accent bars at the top and bottom (`topColorBar` and `bottomFooterBar`) match the assigned track identification color on the main Timeline.
+* **Live Recording (ARM 🔴):** Toggling the ARM button prepares the channel to receive real-time input from a live microphone or hardware MIDI keyboard.
+
+## 4. html
+
+``` html
+<!DOCTYPE html>
+<html lang="vi" class="h-full bg-slate-950 text-slate-100 select-none">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>DAW Track Channel Strip Component</title>
+  <!-- Tailwind CSS -->
+  <script src="https://cdn.tailwindcss.com"></script>
+  <!-- Font Awesome Icons -->
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+  <!-- Fonts -->
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet">
+  
+  <style>
+    body { font-family: 'Inter', sans-serif; }
+    .font-mono { font-family: 'JetBrains Mono', monospace; }
+
+    /* Custom Scrollbar */
+    ::-webkit-scrollbar { width: 6px; height: 6px; }
+    ::-webkit-scrollbar-track { background: #090d16; }
+    ::-webkit-scrollbar-thumb { background: #1e293b; border-radius: 3px; }
+
+    /* REAPER Metallic Dark DAW Styling */
+    .strip-bg {
+      background: linear-gradient(180deg, #2c2c2c 0%, #1e1e1e 100%);
+      border: 1px solid #111111;
+      box-shadow: inset 1px 1px 0 rgba(255,255,255,0.08), 0 10px 30px rgba(0,0,0,0.85);
+    }
+
+    .fader-track-bg {
+      background: #101010;
+      box-shadow: inset 1px 1px 3px rgba(0,0,0,0.9), 1px 1px 0 rgba(255,255,255,0.05);
+    }
+
+    /* DAW Metallic Buttons */
+    .btn-daw {
+      background: linear-gradient(180deg, #3d3d3d 0%, #242424 100%);
+      border: 1px solid #141414;
+      box-shadow: inset 0 1px 0 rgba(255,255,255,0.12), 0 2px 4px rgba(0,0,0,0.6);
+      transition: all 0.1s ease;
+    }
+    .btn-daw:hover {
+      background: linear-gradient(180deg, #4d4d4d 0%, #2f2f2f 100%);
+    }
+    .btn-daw:active {
+      box-shadow: inset 0 2px 4px rgba(0,0,0,0.8);
+      transform: translateY(0.5px);
+    }
+
+    /* Active State Button Styles */
+    .btn-mute-active {
+      background: linear-gradient(180deg, #ef4444 0%, #991b1b 100%) !important;
+      border-color: #f87171 !important;
+      color: #ffffff !important;
+      box-shadow: 0 0 8px rgba(239, 68, 68, 0.6) !important;
+    }
+
+    .btn-solo-active {
+      background: linear-gradient(180deg, #eab308 0%, #854d0e 100%) !important;
+      border-color: #fde047 !important;
+      color: #000000 !important;
+      box-shadow: 0 0 8px rgba(234, 179, 8, 0.6) !important;
+    }
+
+    .btn-arm-active {
+      background: radial-gradient(circle, #ef4444 0%, #7f1d1d 100%) !important;
+      border-color: #fca5a5 !important;
+      box-shadow: 0 0 12px rgba(239, 68, 68, 0.9), inset 0 1px 2px rgba(255,255,255,0.8) !important;
+      animation: pulse-red 1.2s infinite alternate;
+    }
+
+    @keyframes pulse-red {
+      0% { box-shadow: 0 0 6px rgba(239, 68, 68, 0.6); }
+      100% { box-shadow: 0 0 16px rgba(239, 68, 68, 1); }
+    }
+
+    /* FIXED VERTICAL SLIDER STYLING */
+    input[type=range].fader-slider {
+      -webkit-appearance: slider-vertical;
+      appearance: slider-vertical;
+      writing-mode: bt-linear;
+      width: 20px;
+      height: 160px; /* Fixed Height prevents stretching */
+      background: transparent;
+      cursor: pointer;
+      margin: 0;
+      padding: 0;
+    }
+  </style>
+</head>
+<body class="h-screen max-h-screen bg-slate-950 flex flex-col items-center justify-center p-4 overflow-hidden select-none">
+
+  <!-- REAPER STYLE NARROW TRACK STRIP CONSOLE COMPONENT -->
+  <div id="trackStripConsole" class="w-[145px] h-[370px] strip-bg rounded-md flex flex-col justify-between text-slate-300 select-none shadow-2xl relative border border-slate-900 overflow-hidden shrink-0">
+    
+    <!-- 1. TOP TRACK COLOR ACCENT BAR (6px) -->
+    <div id="topColorBar" class="h-1.5 w-full bg-emerald-500 transition-colors shrink-0"></div>
+
+    <!-- 2. PAN ROTARY DIAL AREA (46px) -->
+    <div id="panBoxBg" class="h-[46px] bg-emerald-950/60 border-b border-emerald-700/40 py-1 px-2 flex flex-col items-center justify-center transition-colors shrink-0">
+      <div id="panKnobDial" class="w-6 h-6 rounded-full bg-slate-800 border-2 border-slate-400 relative flex items-center justify-center cursor-pointer shadow-md" title="Kéo chuột lên/xuống để chỉnh Pan (Left/Right)">
+        <div id="panPointer" class="w-0.5 h-2 bg-emerald-300 rounded absolute top-0.5 transition-transform" style="transform: rotate(0deg);"></div>
+      </div>
+      <span id="panText" class="text-[8px] font-mono text-emerald-200 mt-0.5 font-semibold">center</span>
+    </div>
+
+    <!-- 3. CENTER AREA: PEAK DB + NARROW FADER + STEREO VU METER + RIGHT BUTTON STACK (210px) -->
+    <div class="p-1 flex gap-1 justify-between items-stretch h-[210px] shrink-0">
+      
+      <!-- LEFT FADER & VU METER COLUMN -->
+      <div class="flex-1 flex flex-col justify-between items-center bg-black/60 p-1 rounded border border-slate-800/80 h-full">
+        <!-- DB Peak Readout -->
+        <div class="w-full flex justify-center text-[8px] font-mono text-slate-400 h-4 items-center">
+          <span id="peakDbVal">-inf</span>
+        </div>
+
+        <!-- Track Fader Rail & VU Meter Dual Column -->
+        <div class="flex items-center justify-around w-full h-[175px] relative py-1">
+          <!-- Track Fader Rail Line & Slider -->
+          <div class="relative fader-track-bg w-3 h-[165px] rounded flex items-center justify-center">
+            <div class="w-0.5 h-full bg-slate-700 absolute"></div>
+            <!-- Vertical Volume Slider (-60dB to +12dB) -->
+            <input id="volumeFader" type="range" min="-60" max="12" step="0.5" value="0" orient="vertical"
+                   class="fader-slider z-10" title="Chỉnh Volume Track (Fader)">
+          </div>
+
+          <!-- Vertical LED Stereo Peak VU Meter Canvas -->
+          <div class="w-2.5 h-[165px] bg-slate-950 rounded border border-slate-900 overflow-hidden relative" title="Peak VU Meter">
+            <canvas id="trackVuCanvas" class="w-full h-full block"></canvas>
+          </div>
+        </div>
+      </div>
+
+      <!-- RIGHT SIDE BUTTON STACK (M, S, ROUTE, FX, POWER, AUTOMATION, PHASE INVERT) -->
+      <div class="w-7 flex flex-col justify-between h-full text-[8px] font-bold shrink-0">
+        <button id="muteBtn" class="btn-daw h-[24px] rounded text-amber-500 font-extrabold flex items-center justify-center" title="Mute Track (Tắt tiếng)">M</button>
+        <button id="soloBtn" class="btn-daw h-[24px] rounded text-yellow-400 font-extrabold flex items-center justify-center" title="Solo Track (Phát đơn độc)">S</button>
+        <button class="btn-daw h-[24px] rounded text-emerald-400 flex items-center justify-center" title="Routing Matrix (Định tuyến I/O)"><i class="fa-solid fa-bars-staggered text-[8px]"></i></button>
+        <button id="fxBtn" class="btn-daw h-[24px] rounded text-slate-300 font-semibold flex items-center justify-center text-[7px]" title="Track FX Chain">FX</button>
+        <button id="powerBtn" class="btn-daw h-[24px] rounded text-emerald-400 flex items-center justify-center text-[8px]" title="Toggle FX Power (Bật/Tắt FX)"><i class="fa-solid fa-power-off"></i></button>
+        <button class="btn-daw h-[24px] rounded text-slate-400 flex items-center justify-center" title="Automation Envelopes"><i class="fa-solid fa-chart-line text-[8px]"></i></button>
+        <button id="phaseBtn" class="btn-daw h-[24px] rounded text-slate-400 flex items-center justify-center text-[9px]" title="Phase Invert (Ø - Đảo pha)">Ø</button>
+      </div>
+
+    </div>
+
+    <!-- 4. RECORD ARM BUTTON ROW (28px) -->
+    <div class="h-[28px] flex items-center justify-between mx-1.5 px-1.5 bg-black/40 rounded border border-slate-800/60 shrink-0">
+      <i class="fa-solid fa-volume-high text-[9px] text-slate-400" title="Input Monitoring"></i>
+      <!-- ARM RECORD BUTTON -->
+      <button id="armBtn" class="w-5 h-5 rounded-full bg-red-950 border-2 border-red-800 flex items-center justify-center text-red-500 transition-all shadow-inner" title="Arm for Recording (Sẵn sàng thu âm)">
+        <i class="fa-solid fa-circle text-[8px]"></i>
+      </button>
+    </div>
+
+    <!-- 5. TRACK NAME IDENTIFIER (26px) -->
+    <div class="h-[26px] mx-1.5 flex items-center justify-center bg-slate-950/80 rounded border border-slate-800/80 shrink-0">
+      <span id="trackNameText" class="text-[11px] font-bold text-emerald-400 tracking-wider font-sans uppercase">Piano</span>
+    </div>
+
+    <!-- 6. TRACK COLOR FOOTER BAR (22px) -->
+    <div id="bottomFooterBar" class="h-[22px] w-full bg-emerald-500 text-slate-950 flex items-center justify-center font-extrabold text-xs font-mono tracking-widest transition-colors shrink-0">
+      1
+    </div>
+
+  </div>
+
+  <script>
+    // Audio Context & State Management
+    let audioCtx = null;
+    let trackGainNode = null;
+    let trackPanNode = null;
+    let analyserNode = null;
+    let synthOsc = null;
+    let isPlaying = false;
+
+    const trackState = {
+      volumeDb: 0.0,
+      pan: 0.0,
+      isMuted: false,
+      isSoloed: false,
+      isArmed: false,
+      isFxActive: true,
+      isPhaseInverted: false
+    };
+
+    // DOM Elements
+    const volumeFader = document.getElementById('volumeFader');
+    const peakDbVal = document.getElementById('peakDbVal');
+    const panKnobDial = document.getElementById('panKnobDial');
+    const panPointer = document.getElementById('panPointer');
+    const panText = document.getElementById('panText');
+    const muteBtn = document.getElementById('muteBtn');
+    const soloBtn = document.getElementById('soloBtn');
+    const armBtn = document.getElementById('armBtn');
+    const powerBtn = document.getElementById('powerBtn');
+    const phaseBtn = document.getElementById('phaseBtn');
+    const vuCanvas = document.getElementById('trackVuCanvas');
+    const vuCtx = vuCanvas.getContext('2d');
+
+    function initAudioEngine() {
+      if (audioCtx) return;
+      const AudioCtxClass = window.AudioContext || window.webkitAudioContext;
+      audioCtx = new AudioCtxClass();
+
+      trackGainNode = audioCtx.createGain();
+      trackPanNode = audioCtx.createStereoPanner ? audioCtx.createStereoPanner() : null;
+      analyserNode = audioCtx.createAnalyser();
+      analyserNode.fftSize = 256;
+
+      if (trackPanNode) {
+        trackGainNode.connect(trackPanNode);
+        trackPanNode.connect(analyserNode);
+      } else {
+        trackGainNode.connect(analyserNode);
+      }
+      analyserNode.connect(audioCtx.destination);
+
+      updateAudioNodes();
+    }
+
+    function updateAudioNodes() {
+      if (!audioCtx) return;
+      const now = audioCtx.currentTime;
+
+      let linearGain = 0;
+      if (!trackState.isMuted) {
+        const db = trackState.volumeDb;
+        linearGain = db <= -60 ? 0 : Math.pow(10, db / 20);
+      }
+
+      if (trackState.isPhaseInverted) {
+        linearGain = -linearGain;
+      }
+
+      trackGainNode.gain.setTargetAtTime(linearGain, now, 0.01);
+
+      if (trackPanNode) {
+        trackPanNode.pan.setTargetAtTime(trackState.pan, now, 0.01);
+      }
+    }
+
+    // Play Synth Sound Preview when interacting with controls
+    function playPreviewNote() {
+      initAudioEngine();
+      if (audioCtx.state === 'suspended') audioCtx.resume();
+
+      if (synthOsc) {
+        try { synthOsc.stop(); } catch(e){}
+        synthOsc.disconnect();
+      }
+
+      synthOsc = audioCtx.createOscillator();
+      const oscGain = audioCtx.createGain();
+
+      synthOsc.type = 'triangle';
+      synthOsc.frequency.setValueAtTime(440, audioCtx.currentTime); // Note A4
+
+      oscGain.gain.setValueAtTime(0.3, audioCtx.currentTime);
+      oscGain.gain.exponentialRampToValueAtTime(0.001, audioCtx.currentTime + 1.2);
+
+      synthOsc.connect(oscGain);
+      oscGain.connect(trackGainNode);
+
+      synthOsc.start();
+      synthOsc.stop(audioCtx.currentTime + 1.2);
+      isPlaying = true;
+    }
+
+    // Volume Slider Event
+    volumeFader.addEventListener('input', (e) => {
+      const db = parseFloat(e.target.value);
+      trackState.volumeDb = db;
+      updateAudioNodes();
+      playPreviewNote();
+    });
+
+    // Rotary Pan Knob Dragging
+    let isPanDragging = false;
+    let panStartY = 0;
+    let startPanVal = 0;
+
+    panKnobDial.addEventListener('pointerdown', (e) => {
+      isPanDragging = true;
+      panStartY = e.clientY;
+      startPanVal = trackState.pan;
+      panKnobDial.setPointerCapture(e.pointerId);
+    });
+
+    panKnobDial.addEventListener('pointermove', (e) => {
+      if (!isPanDragging) return;
+      const deltaY = panStartY - e.clientY;
+      let newPan = startPanVal + (deltaY / 80);
+      newPan = Math.min(1.0, Math.max(-1.0, newPan));
+
+      trackState.pan = newPan;
+      const angle = newPan * 120;
+      panPointer.style.transform = `rotate(${angle}deg)`;
+
+      if (newPan === 0) panText.innerText = 'center';
+      else if (newPan < 0) panText.innerText = `L${Math.abs(Math.round(newPan * 100))}`;
+      else panText.innerText = `R${Math.round(newPan * 100)}`;
+
+      updateAudioNodes();
+      playPreviewNote();
+    });
+
+    panKnobDial.addEventListener('pointerup', (e) => {
+      isPanDragging = false;
+      try { panKnobDial.releasePointerCapture(e.pointerId); } catch(err){}
+    });
+
+    // Buttons Interactions
+    muteBtn.addEventListener('click', () => {
+      trackState.isMuted = !trackState.isMuted;
+      muteBtn.classList.toggle('btn-mute-active', trackState.isMuted);
+      updateAudioNodes();
+    });
+
+    soloBtn.addEventListener('click', () => {
+      trackState.isSoloed = !trackState.isSoloed;
+      soloBtn.classList.toggle('btn-solo-active', trackState.isSoloed);
+    });
+
+    armBtn.addEventListener('click', () => {
+      trackState.isArmed = !trackState.isArmed;
+      armBtn.classList.toggle('btn-arm-active', trackState.isArmed);
+    });
+
+    powerBtn.addEventListener('click', () => {
+      trackState.isFxActive = !trackState.isFxActive;
+      powerBtn.classList.toggle('text-slate-500', !trackState.isFxActive);
+      powerBtn.classList.toggle('text-emerald-400', trackState.isFxActive);
+    });
+
+    phaseBtn.addEventListener('click', () => {
+      trackState.isPhaseInverted = !trackState.isPhaseInverted;
+      phaseBtn.classList.toggle('bg-amber-600', trackState.isPhaseInverted);
+      phaseBtn.classList.toggle('text-white', trackState.isPhaseInverted);
+      updateAudioNodes();
+    });
+
+    // Peak VU Meter Renderer
+    function renderVuMeter() {
+      requestAnimationFrame(renderVuMeter);
+
+      vuCanvas.width = vuCanvas.clientWidth;
+      vuCanvas.height = vuCanvas.clientHeight;
+
+      const w = vuCanvas.width;
+      const h = vuCanvas.height;
+
+      vuCtx.clearRect(0, 0, w, h);
+
+      let level = 0;
+      if (isPlaying && !trackState.isMuted) {
+        const db = trackState.volumeDb;
+        const linearGain = db <= -60 ? 0 : Math.pow(10, db / 20);
+        level = (0.25 + Math.random() * 0.6) * linearGain;
+      }
+
+      const barH = level * h;
+      const grad = vuCtx.createLinearGradient(0, h, 0, 0);
+      grad.addColorStop(0, '#10b981');
+      grad.addColorStop(0.7, '#f59e0b');
+      grad.addColorStop(0.95, '#ef4444');
+
+      vuCtx.fillStyle = grad;
+      vuCtx.fillRect(1, h - barH, w - 2, barH);
+
+      if (level > 0) {
+        const dbVal = (20 * Math.log10(level)).toFixed(1);
+        peakDbVal.innerText = `${dbVal}dB`;
+      } else {
+        peakDbVal.innerText = '-inf';
+      }
+    }
+
+    renderVuMeter();
+  </script>
+</body>
+</html>
+```

md/49_AI_PROMPT_GENERATOR.md

@@ -0,0 +1,908 @@
+<!DOCTYPE html>
+<html lang="vi" class="h-full bg-slate-950 text-slate-100 select-none">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>MIDI AI Prompt Generator & Preset Builder</title>
+  <!-- Tailwind CSS -->
+  <script src="https://cdn.tailwindcss.com"></script>
+  <!-- Font Awesome Icons -->
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+  <!-- Fonts -->
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet">
+  
+  <style>
+    body { font-family: 'Inter', sans-serif; }
+    .font-mono { font-family: 'JetBrains Mono', monospace; }
+
+    /* Custom Scrollbar */
+    ::-webkit-scrollbar { width: 6px; height: 6px; }
+    ::-webkit-scrollbar-track { background: #090d16; }
+    ::-webkit-scrollbar-thumb { background: #1e293b; border-radius: 3px; }
+    ::-webkit-scrollbar-thumb:hover { background: #334155; }
+
+    /* Form Panels */
+    .panel-bg {
+      background: linear-gradient(180deg, #111827 0%, #0f172a 100%);
+      border: 1px solid rgba(255, 255, 255, 0.08);
+    }
+  </style>
+</head>
+<body class="h-full flex flex-col bg-slate-950 text-slate-200 overflow-hidden">
+
+  <!-- TOP HEADER TOOLBAR -->
+  <header class="h-14 bg-slate-900 border-b border-slate-800 px-5 flex items-center justify-between z-20 shrink-0">
+    <div class="flex items-center gap-3">
+      <div class="w-9 h-9 rounded-xl bg-gradient-to-tr from-cyan-600 to-indigo-600 flex items-center justify-center text-white shadow-lg shadow-cyan-950">
+        <i class="fa-solid fa-wand-magic-sparkles text-sm"></i>
+      </div>
+      <div>
+        <h1 class="text-sm font-bold tracking-wide text-white flex items-center gap-2">
+          MIDI AI PROMPT GENERATOR <span class="text-[10px] bg-cyan-950 text-cyan-400 border border-cyan-800/80 px-1.5 py-0.5 rounded font-mono">FULL BEAT COVERAGE</span>
+        </h1>
+        <p class="text-[11px] text-slate-400">Công cụ tạo mẫu Prompt nhạc lý ép AI sinh đủ nốt phủ kín số ô nhịp</p>
+      </div>
+    </div>
+
+    <!-- Right Header Actions -->
+    <div class="flex items-center gap-2">
+      <button id="btnLoadDefaultPreset" class="px-3 py-1.5 bg-slate-800 hover:bg-slate-700 text-slate-300 rounded-lg text-xs font-semibold flex items-center gap-1.5 border border-slate-700 transition-colors">
+        <i class="fa-solid fa-rotate-left text-cyan-400"></i> Nạp Mẫu Piano
+      </button>
+      <button id="btnExportJSON" class="px-3 py-1.5 bg-slate-800 hover:bg-slate-700 text-slate-300 rounded-lg text-xs font-semibold flex items-center gap-1.5 border border-slate-700 transition-colors">
+        <i class="fa-solid fa-download"></i> Xuất Preset JSON
+      </button>
+      <label id="btnImportJSON" class="px-3 py-1.5 bg-slate-800 hover:bg-slate-700 text-slate-300 rounded-lg text-xs font-semibold flex items-center gap-1.5 border border-slate-700 cursor-pointer transition-colors">
+        <i class="fa-solid fa-upload"></i> Nhập JSON
+        <input type="file" id="jsonFileInput" accept=".json" class="hidden">
+      </label>
+    </div>
+  </header>
+
+  <!-- MAIN WORKSPACE -->
+  <main class="flex-1 grid grid-cols-12 overflow-hidden">
+    
+    <!-- LEFT COLUMN: FORM CONTROLS (WIDTH: 7 COLS) -->
+    <div class="col-span-7 border-r border-slate-800/80 p-5 overflow-y-auto space-y-5 custom-scrollbar bg-slate-950/60">
+      
+      <!-- 1. VAI TRÒ & PHONG CÁCH -->
+      <section class="panel-bg rounded-xl p-4 space-y-3">
+        <div class="flex items-center gap-2 text-xs font-bold text-cyan-400 uppercase tracking-wider border-b border-slate-800/80 pb-2">
+          <i class="fa-solid fa-user-ninja"></i> 1. Vai Trò Nghệ Sĩ & Phong Cách
+        </div>
+
+        <div class="grid grid-cols-2 gap-3 text-xs">
+          <div>
+            <label class="block text-slate-400 mb-1 font-medium">Vai trò / Chuyên môn:</label>
+            <input type="text" id="inputRole" list="roleDatalist" class="w-full bg-slate-900 border border-slate-800 rounded-lg px-3 py-2 text-white focus:outline-none focus:border-cyan-500 font-sans" value="nghệ sĩ piano chuyên nghiệp và là nhà soạn nhạc phim" placeholder="Chọn hoặc nhập vai trò mới...">
+            <datalist id="roleDatalist"></datalist>
+          </div>
+          <div>
+            <label class="block text-slate-400 mb-1 font-medium">Hành động / Thể loại đoạn nhạc:</label>
+            <input type="text" id="inputActionDesc" list="actionDatalist" class="w-full bg-slate-900 border border-slate-800 rounded-lg px-3 py-2 text-white focus:outline-none focus:border-cyan-500 font-sans" value="tiếp tục bản nhạc piano đầy cảm xúc này" placeholder="Chọn hoặc nhập hành động mới...">
+            <datalist id="actionDatalist"></datalist>
+          </div>
+        </div>
+
+        <div class="grid grid-cols-2 gap-3 text-xs">
+          <div>
+            <label class="block text-slate-400 mb-1 font-medium">Loại Phân đoạn (Section Type):</label>
+            <input type="text" id="inputSectionType" list="sectionTypeDatalist" class="w-full bg-slate-900 border border-slate-800 rounded-lg px-3 py-2 text-white focus:outline-none focus:border-cyan-500 font-sans" value="Cao trào (Build-Up) kịch tính" placeholder="Chọn hoặc nhập phân đoạn mới...">
+            <datalist id="sectionTypeDatalist"></datalist>
+          </div>
+          <div>
+            <label class="block text-slate-400 mb-1 font-medium">Tên Tool AI Gọi (Function Tool Name):</label>
+            <input type="text" id="inputToolName" class="w-full bg-slate-900 border border-slate-800 rounded-lg px-3 py-2 text-cyan-400 font-mono focus:outline-none focus:border-cyan-500" value="generate_multitrack_midi">
+          </div>
+        </div>
+      </section>
+
+      <!-- 2. Ô NHỊP & PHÁCH (BARS & BEATS COMPUTATION) -->
+      <section class="panel-bg rounded-xl p-4 space-y-3">
+        <div class="flex items-center justify-between border-b border-slate-800/80 pb-2">
+          <div class="flex items-center gap-2 text-xs font-bold text-amber-400 uppercase tracking-wider">
+            <i class="fa-solid fa-stopwatch"></i> 2. Ô Nhịp & Phách (Bars & Beats Auto-Calc)
+          </div>
+          <span class="text-[10px] font-mono bg-amber-950/80 border border-amber-800/60 text-amber-300 px-2 py-0.5 rounded">Auto-Computed</span>
+        </div>
+
+        <div class="grid grid-cols-4 gap-3 text-xs">
+          <div>
+            <label class="block text-slate-400 mb-1 font-medium">Ô nhịp Bắt đầu:</label>
+            <input type="number" id="inputStartBar" min="1" max="999" value="9" class="w-full bg-slate-900 border border-slate-800 rounded-lg px-3 py-2 text-white font-mono focus:outline-none focus:border-amber-500">
+          </div>
+          <div>
+            <label class="block text-slate-400 mb-1 font-medium">Ô nhịp Kết thúc:</label>
+            <input type="number" id="inputEndBar" min="1" max="999" value="16" class="w-full bg-slate-900 border border-slate-800 rounded-lg px-3 py-2 text-white font-mono focus:outline-none focus:border-amber-500">
+          </div>
+          <div>
+            <label class="block text-slate-400 mb-1 font-medium">Số phách/Ô nhịp (Time Sig):</label>
+            <select id="selectBeatsPerBar" class="w-full bg-slate-900 border border-slate-800 rounded-lg px-3 py-2 text-amber-300 font-mono focus:outline-none focus:border-amber-500">
+              <option value="4">4 Phách (Nhịp 4/4)</option>
+              <option value="3">3 Phách (Nhịp 3/4 Waltz)</option>
+              <option value="6">6 Phách (Nhịp 6/8)</option>
+            </select>
+          </div>
+          <div>
+            <label class="block text-slate-400 mb-1 font-medium">Quy đổi Tổng Số Phách:</label>
+            <div id="readoutTotalBeats" class="w-full bg-slate-950 border border-amber-900/60 rounded-lg px-3 py-2 text-amber-400 font-mono font-bold">
+              64.0 Phách
+            </div>
+          </div>
+        </div>
+
+        <div class="text-[11px] font-mono bg-slate-950 p-2.5 rounded-lg border border-slate-800 text-slate-400 flex items-center justify-between">
+          <span>Chuỗi Ô nhịp tự động sinh:</span>
+          <span id="readoutBarList" class="text-cyan-300 font-bold">9, 10, 11, 12, 13, 14, 15 và 16</span>
+        </div>
+      </section>
+
+      <!-- 3. MẬT ĐỘ NỐT & QUY TẮC HIỆU NĂNG -->
+      <section class="panel-bg rounded-xl p-4 space-y-3">
+        <div class="flex items-center gap-2 text-xs font-bold text-emerald-400 uppercase tracking-wider border-b border-slate-800/80 pb-2">
+          <i class="fa-solid fa-gauge-simple-high"></i> 3. Mật Độ Nốt & Giới Hạn Token
+        </div>
+
+        <div class="text-xs">
+          <label class="block text-slate-400 mb-1 font-medium">Hướng dẫn Mật độ Nốt (Note Density Instruction):</label>
+          <textarea id="inputDensityRule" rows="2" class="w-full bg-slate-900 border border-slate-800 rounded-lg p-3 text-white font-sans focus:outline-none focus:border-emerald-500 leading-relaxed text-xs">Hãy giữ mật độ nốt hiệu quả (chủ yếu là nốt đen và các đoạn rải hợp âm nốt móc đơn đều đặn, tránh các chuỗi nốt móc đôi/móc ba quá dày đặc) để tránh bị quá giới hạn thời gian xuất dữ liệu (token timeout).</textarea>
+        </div>
+      </section>
+
+      <!-- 4. DANH SÁCH TRACKS (DYNAMIC TRACKS EDITOR) -->
+      <section class="panel-bg rounded-xl p-4 space-y-3">
+        <div class="flex items-center justify-between border-b border-slate-800/80 pb-2">
+          <div class="flex items-center gap-2 text-xs font-bold text-indigo-400 uppercase tracking-wider">
+            <i class="fa-solid fa-layer-group"></i> 4. Danh Sách Track Cấu Trúc (<span id="trackCountBadge">3</span> Tracks)
+          </div>
+          <button id="btnAddTrack" class="px-2.5 py-1 bg-indigo-600 hover:bg-indigo-500 text-white rounded text-xs font-bold transition-all flex items-center gap-1 shadow-md shadow-indigo-950">
+            <i class="fa-solid fa-plus text-[10px]"></i> Thêm Track
+          </button>
+        </div>
+
+        <!-- Datalists for Track Names and Track Labels History -->
+        <datalist id="trackNameDatalist"></datalist>
+        <datalist id="trackLabelDatalist"></datalist>
+
+        <!-- Tracks Container -->
+        <div id="tracksContainer" class="space-y-3">
+          <!-- Dynamic Track Cards Rendered via JS -->
+        </div>
+      </section>
+
+    </div>
+
+    <!-- RIGHT COLUMN: LIVE PROMPT PREVIEW & COPY (WIDTH: 5 COLS) -->
+    <div class="col-span-5 bg-slate-900 flex flex-col overflow-hidden relative">
+      
+      <!-- Preview Header -->
+      <div class="h-10 shrink-0 bg-slate-950 border-b border-slate-800 px-4 flex items-center justify-between text-xs font-mono">
+        <span class="text-slate-300 font-bold flex items-center gap-2">
+          <i class="fa-solid fa-code text-cyan-400"></i> LIVE PROMPT PREVIEW
+        </span>
+        <div class="flex items-center gap-2">
+          <button id="btnCopyPrompt" class="px-2.5 py-1 bg-slate-800 hover:bg-slate-700 text-slate-300 font-sans font-semibold text-xs rounded flex items-center gap-1 transition-all border border-slate-700" title="Sao Chép Văn Bản">
+            <i class="fa-solid fa-copy text-cyan-400"></i> <span>Sao Chép</span>
+          </button>
+          <button id="btnSavePresetModal" class="px-3 py-1 bg-purple-600 hover:bg-purple-500 text-white font-sans font-bold text-xs rounded flex items-center gap-1.5 transition-all shadow-md shadow-purple-950">
+            <i class="fa-solid fa-bookmark"></i> <span>Lưu thành Preset</span>
+          </button>
+        </div>
+      </div>
+
+      <!-- Live Generated Text Output Box -->
+      <div class="flex-1 flex flex-col min-h-0 p-4">
+        <div id="promptOutputText" class="w-full flex-1 bg-slate-950 border border-slate-800 rounded-xl p-4 font-mono text-xs text-slate-200 leading-relaxed whitespace-pre-wrap select-text selection:bg-cyan-900 selection:text-white overflow-y-auto custom-scrollbar">
+          <!-- Text generated dynamically -->
+        </div>
+      </div>
+
+      <!-- Toast Notification Container -->
+      <div id="toastNotification" class="absolute bottom-5 right-5 bg-emerald-600 text-white px-4 py-2.5 rounded-xl shadow-2xl font-semibold text-xs flex items-center gap-2 transition-all duration-300 transform translate-y-10 opacity-0 pointer-events-none z-50">
+        <i class="fa-solid fa-circle-check text-base"></i>
+        <span id="toastMessage">Đã sao chép câu Prompt vào bộ nhớ tạm!</span>
+      </div>
+
+    </div>
+
+  </main>
+
+  <!-- MODAL: AI PROMPT PRESET MANAGER (FORM TẠO PRESET MỚI) -->
+  <div id="presetManagerModal" class="fixed inset-0 bg-black/80 backdrop-blur-md z-50 flex items-center justify-center hidden p-4">
+    <div class="w-full max-w-3xl bg-[#13141a] border border-slate-800 rounded-2xl shadow-2xl p-6 space-y-4 text-slate-200 relative overflow-hidden">
+      
+      <!-- Header -->
+      <div class="flex items-center justify-between border-b border-slate-800/80 pb-3">
+        <h2 class="text-sm font-bold tracking-widest text-transparent bg-clip-text bg-gradient-to-r from-purple-400 via-pink-400 to-indigo-400 font-mono uppercase">
+          AI PROMPT PRESET MANAGER
+        </h2>
+        <button id="btnCloseModalX" class="w-7 h-7 rounded-lg bg-slate-800 hover:bg-slate-700 text-slate-400 hover:text-white flex items-center justify-center transition-colors">
+          <i class="fa-solid fa-xmark"></i>
+        </button>
+      </div>
+
+      <!-- Section Title -->
+      <div class="text-xs font-bold text-slate-300 uppercase tracking-wider font-mono flex items-center gap-2">
+        <i class="fa-solid fa-wand-magic-sparkles text-purple-400"></i> TẠO PRESET MỚI
+      </div>
+
+      <!-- Preset Form Grid -->
+      <div class="space-y-3 text-xs">
+        
+        <!-- Row 1: Name & Category -->
+        <div class="grid grid-cols-2 gap-3">
+          <div>
+            <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">TÊN PRESET</label>
+            <input type="text" id="presetNameInput" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white focus:outline-none focus:border-purple-500 font-sans" placeholder="Nhập tên preset (VD: Epic Orchestra Intro)...">
+          </div>
+          <div>
+            <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">DANH MỤC</label>
+            <select id="presetCategorySelect" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white focus:outline-none focus:border-purple-500 font-sans">
+              <option value="Orchestral / Film Score">Orchestral / Film Score</option>
+              <option value="Piano Solo">Piano Solo</option>
+              <option value="EDM / Pop">EDM / Pop</option>
+              <option value="Cinematic">Cinematic</option>
+              <option value="Jazz & Swing">Jazz & Swing</option>
+              <option value="Lo-fi Chillhop">Lo-fi Chillhop</option>
+            </select>
+          </div>
+        </div>
+
+        <!-- Row 2: Keywords -->
+        <div>
+          <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">TỪ KHÓA KÍCH HOẠT (NGĂN CÁCH BẰNG DẤU PHẨY)</label>
+          <input type="text" id="presetKeywordsInput" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white focus:outline-none focus:border-purple-500 font-sans" placeholder="Ví dụ: epic orchestra, hoành tráng, nhạc phim epic">
+        </div>
+
+        <!-- Row 3: Bars, BPM, Scale -->
+        <div class="grid grid-cols-3 gap-3">
+          <div>
+            <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">SỐ BARS MẶC ĐỊNH</label>
+            <input type="number" id="presetBarsInput" value="8" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white font-mono focus:outline-none focus:border-purple-500">
+          </div>
+          <div>
+            <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">BPM MẶC ĐỊNH</label>
+            <input type="number" id="presetBpmInput" value="120" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white font-mono focus:outline-none focus:border-purple-500">
+          </div>
+          <div>
+            <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">ÂM GIAI (SCALE) MẶC ĐỊNH</label>
+            <input type="text" id="presetScaleInput" value="C Minor" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white font-mono focus:outline-none focus:border-purple-500" placeholder="VD: C Minor, A Major...">
+          </div>
+        </div>
+
+        <!-- Row 4: System Prompt Template -->
+        <div>
+          <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">SYSTEM PROMPT TEMPLATE / LUẬT SOẠN NHẠC</label>
+          <textarea id="presetTemplateTextarea" rows="6" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg p-3 text-white font-mono text-xs focus:outline-none focus:border-purple-500 leading-relaxed custom-scrollbar"></textarea>
+        </div>
+
+      </div>
+
+      <!-- Action Buttons Row -->
+      <div class="space-y-3 pt-2 border-t border-slate-800/80">
+        <div class="flex items-center justify-between">
+          <button id="btnCreateStructuredPreset" class="px-4 py-2 bg-emerald-700 hover:bg-emerald-600 text-white rounded-lg text-xs font-bold transition-all shadow-md flex items-center gap-1.5">
+            <i class="fa-solid fa-wand-magic-sparkles"></i> Tạo preset có cấu trúc
+          </button>
+          <div class="flex items-center gap-2">
+            <button id="btnModalBack" class="px-4 py-2 bg-[#252836] hover:bg-slate-700 text-slate-300 rounded-lg text-xs font-semibold transition-colors">
+              Quay lại
+            </button>
+            <button id="btnSavePresetSubmit" class="px-5 py-2 bg-purple-600 hover:bg-purple-500 text-white rounded-lg text-xs font-bold transition-all shadow-lg shadow-purple-950/80 flex items-center gap-1.5">
+              <i class="fa-solid fa-floppy-disk"></i> <span>Lưu Preset</span>
+            </button>
+          </div>
+        </div>
+        <div class="flex justify-end">
+          <button id="btnCloseModalBottom" class="px-4 py-1.5 bg-[#1f222e] hover:bg-slate-700 text-slate-300 rounded-lg text-xs font-semibold transition-colors">
+            Đóng
+          </button>
+        </div>
+      </div>
+
+    </div>
+  </div>
+
+  <!-- JAVASCRIPT LOGIC & STATE ENGINE -->
+  <script>
+    // Default Template State matching User Specification
+    const state = {
+      role: "nghệ sĩ piano chuyên nghiệp và là nhà soạn nhạc phim",
+      actionDesc: "tiếp tục bản nhạc piano đầy cảm xúc này",
+      sectionType: "Cao trào (Build-Up) kịch tính",
+      startBar: 9,
+      endBar: 16,
+      beatsPerBar: 4,
+      densityRule: "Hãy giữ mật độ nốt hiệu quả (chủ yếu là nốt đen và các đoạn rải hợp âm nốt móc đơn đều đặn, tránh các chuỗi nốt móc đôi/móc ba quá dày đặc) để tránh bị quá giới hạn thời gian xuất dữ liệu (token timeout).",
+      toolName: "generate_multitrack_midi",
+      tracks: [
+        {
+          id: "track_1",
+          name: "Piano Bass & Octaves",
+          label: "Tiếng Bass & Quãng 8 Piano",
+          description: "đánh các xung bass trầm nốt đen đều đặn (trong dải C1-C3) liên tục trên mỗi phách từ phách 0.0 đến phách 64.0 (tổng cộng 64 nốt đen)."
+        },
+        {
+          id: "track_2",
+          name: "Piano Accompaniment",
+          label: "Tiếng Đệm Piano",
+          description: "đánh các đoạn rải hợp âm (broken chord arpeggios) nốt móc đơn có nhịp điệu ở âm vực trung (dải C3-C4), lấp đầy liên tục toàn bộ 8 ô nhịp từ phách 0.0 đến phách 64.0."
+        },
+        {
+          id: "track_3",
+          name: "Piano Melody - Right Hand",
+          label: "Giai điệu Piano - Tay phải",
+          description: "đánh một tuyến giai điệu đi lên ở âm vực cao (dải C4-C6) sử dụng nốt trắng và nốt tròn trải dài từ Ô nhịp 9 đến 16, kết thúc bằng một hợp âm chủ (tonic chord) ngân dài được giữ cho đến phách 64.0."
+        }
+      ]
+    };
+
+    // History & Dropdown Options Management
+    const defaultHistory = {
+      roles: [
+        "nghệ sĩ piano chuyên nghiệp và là nhà soạn nhạc phim",
+        "nhà sản xuất âm nhạc EDM / Electro Pop",
+        "nhà soạn nhạc phim Epic Orchestra hoành tráng",
+        "nghệ sĩ nhạc Jazz ngẫu hứng chuyên nghiệp",
+        "nhà sản xuất nhạc Lo-fi Chillhop & Beatmaker"
+      ],
+      actions: [
+        "tiếp tục bản nhạc piano đầy cảm xúc này",
+        "tạo một đoạn nhạc dồn dập kịch tính",
+        "phát triển giai điệu mở đầu du dương",
+        "xây dựng đoạn điệp khúc bùng nổ và hoành tráng"
+      ],
+      sectionTypes: [
+        "Cao trào (Build-Up) kịch tính",
+        "Mở đầu (Intro) du dương",
+        "Điệp khúc (Chorus / Climax) bùng nổ",
+        "Đoạn lắng (Breakdown / Interlude)",
+        "Đoạn kết (Outro / Resolution)"
+      ],
+      trackNames: [
+        "Piano Bass & Octaves",
+        "Piano Accompaniment",
+        "Piano Melody - Right Hand",
+        "Strings Ensemble",
+        "Brass Theme",
+        "Epic Percussion",
+        "Synth Lead",
+        "Bassline"
+      ],
+      trackLabels: [
+        "Tiếng Bass & Quãng 8 Piano",
+        "Tiếng Đệm Piano",
+        "Giai điệu Piano - Tay phải",
+        "Dàn dây Ostinato",
+        "Tuyến Kèn Brass",
+        "Bộ Trống Epic",
+        "Giai điệu Synth",
+        "Tuyến Bass Sub"
+      ]
+    };
+
+    // DOM References
+    const inputRole = document.getElementById('inputRole');
+    const inputActionDesc = document.getElementById('inputActionDesc');
+    const inputSectionType = document.getElementById('inputSectionType');
+    const inputToolName = document.getElementById('inputToolName');
+    const roleDatalist = document.getElementById('roleDatalist');
+    const actionDatalist = document.getElementById('actionDatalist');
+    const sectionTypeDatalist = document.getElementById('sectionTypeDatalist');
+    const inputStartBar = document.getElementById('inputStartBar');
+    const inputEndBar = document.getElementById('inputEndBar');
+    const selectBeatsPerBar = document.getElementById('selectBeatsPerBar');
+    const inputDensityRule = document.getElementById('inputDensityRule');
+    const readoutTotalBeats = document.getElementById('readoutTotalBeats');
+    const readoutBarList = document.getElementById('readoutBarList');
+    const tracksContainer = document.getElementById('tracksContainer');
+    const trackCountBadge = document.getElementById('trackCountBadge');
+    const promptOutputText = document.getElementById('promptOutputText');
+    const btnAddTrack = document.getElementById('btnAddTrack');
+    const btnCopyPrompt = document.getElementById('btnCopyPrompt');
+    const btnLoadDefaultPreset = document.getElementById('btnLoadDefaultPreset');
+    const btnExportJSON = document.getElementById('btnExportJSON');
+    const jsonFileInput = document.getElementById('jsonFileInput');
+    const toastNotification = document.getElementById('toastNotification');
+
+    // Preset Modal Elements
+    const presetManagerModal = document.getElementById('presetManagerModal');
+    const btnSavePresetModal = document.getElementById('btnSavePresetModal');
+    const btnCloseModalX = document.getElementById('btnCloseModalX');
+    const btnCloseModalBottom = document.getElementById('btnCloseModalBottom');
+    const btnModalBack = document.getElementById('btnModalBack');
+    const btnSavePresetSubmit = document.getElementById('btnSavePresetSubmit');
+    const btnCreateStructuredPreset = document.getElementById('btnCreateStructuredPreset');
+    const presetNameInput = document.getElementById('presetNameInput');
+    const presetCategorySelect = document.getElementById('presetCategorySelect');
+    const presetKeywordsInput = document.getElementById('presetKeywordsInput');
+    const presetBarsInput = document.getElementById('presetBarsInput');
+    const presetBpmInput = document.getElementById('presetBpmInput');
+    const presetScaleInput = document.getElementById('presetScaleInput');
+    const presetTemplateTextarea = document.getElementById('presetTemplateTextarea');
+
+    // LocalStorage Helper Functions for History
+    function getHistory(key, defaults) {
+      try {
+        const saved = localStorage.getItem(`midi_prompt_history_${key}`);
+        return saved ? JSON.parse(saved) : defaults;
+      } catch (e) {
+        return defaults;
+      }
+    }
+
+    function saveHistoryItem(key, newValue, defaults) {
+      const val = (newValue || "").trim();
+      if (!val) return;
+      let list = getHistory(key, defaults);
+      if (!list.includes(val)) {
+        list.unshift(val); // Put newest entry first
+        try {
+          localStorage.setItem(`midi_prompt_history_${key}`, JSON.stringify(list));
+        } catch (e) {}
+        renderDatalistOptions(key, list);
+      }
+    }
+
+    function renderDatalistOptions(key, list) {
+      let datalistElem;
+      if (key === 'roles') datalistElem = roleDatalist;
+      else if (key === 'actions') datalistElem = actionDatalist;
+      else if (key === 'sectionTypes') datalistElem = sectionTypeDatalist;
+      else if (key === 'trackNames') datalistElem = document.getElementById('trackNameDatalist');
+      else if (key === 'trackLabels') datalistElem = document.getElementById('trackLabelDatalist');
+
+      if (!datalistElem) return;
+      datalistElem.innerHTML = list.map(item => `<option value="${escapeHtml(item)}"></option>`).join('');
+    }
+
+    function initHistoryDatalists() {
+      const roles = getHistory('roles', defaultHistory.roles);
+      const actions = getHistory('actions', defaultHistory.actions);
+      const sectionTypes = getHistory('sectionTypes', defaultHistory.sectionTypes);
+      const trackNames = getHistory('trackNames', defaultHistory.trackNames);
+      const trackLabels = getHistory('trackLabels', defaultHistory.trackLabels);
+
+      renderDatalistOptions('roles', roles);
+      renderDatalistOptions('actions', actions);
+      renderDatalistOptions('sectionTypes', sectionTypes);
+      renderDatalistOptions('trackNames', trackNames);
+      renderDatalistOptions('trackLabels', trackLabels);
+    }
+
+    // Auto-save history on input change/blur
+    inputRole.addEventListener('change', () => saveHistoryItem('roles', inputRole.value, defaultHistory.roles));
+    inputActionDesc.addEventListener('change', () => saveHistoryItem('actions', inputActionDesc.value, defaultHistory.actions));
+    inputSectionType.addEventListener('change', () => saveHistoryItem('sectionTypes', inputSectionType.value, defaultHistory.sectionTypes));
+
+    // Helper to calculate total bars, total beats, and format bar range list
+    function computeTimeMetrics() {
+      const start = parseInt(inputStartBar.value) || 1;
+      const end = parseInt(inputEndBar.value) || 1;
+      const beatsPerBar = parseInt(selectBeatsPerBar.value) || 4;
+
+      const barCount = Math.max(1, (end - start) + 1);
+      const totalBeats = (barCount * beatsPerBar).toFixed(1);
+
+      // Format bar list string: e.g. "9, 10, 11, 12, 13, 14, 15 và 16"
+      const barNumbers = [];
+      for (let i = start; i <= end; i++) {
+        barNumbers.push(i);
+      }
+
+      let barListStr = "";
+      if (barNumbers.length === 1) {
+        barListStr = `${barNumbers[0]}`;
+      } else if (barNumbers.length === 2) {
+        barListStr = `${barNumbers[0]} và ${barNumbers[1]}`;
+      } else {
+        const leading = barNumbers.slice(0, -1).join(', ');
+        const last = barNumbers[barNumbers.length - 1];
+        barListStr = `${leading} và ${last}`;
+      }
+
+      readoutTotalBeats.innerText = `${totalBeats} Phách`;
+      readoutBarList.innerText = barListStr;
+
+      return {
+        barCount,
+        totalBeats,
+        start,
+        end,
+        barListStr
+      };
+    }
+
+    // Render Dynamic Track Input Cards
+    function renderTrackEditors() {
+      tracksContainer.innerHTML = "";
+      trackCountBadge.innerText = state.tracks.length;
+
+      state.tracks.forEach((track, idx) => {
+        const card = document.createElement('div');
+        card.className = "bg-slate-900/90 border border-slate-800 p-3 rounded-xl space-y-2 relative group";
+        
+        card.innerHTML = `
+          <div class="flex items-center justify-between text-xs font-bold text-slate-300">
+            <span class="flex items-center gap-2">
+              <span class="w-5 h-5 rounded-full bg-slate-800 border border-slate-700 flex items-center justify-center text-[10px] text-cyan-400 font-mono">${idx + 1}</span>
+              Track ${idx + 1}
+            </span>
+            <div class="flex items-center gap-1">
+              <button onclick="moveTrack(${idx}, -1)" class="w-6 h-6 rounded bg-slate-800 hover:bg-slate-700 text-slate-400 hover:text-white flex items-center justify-center transition-colors" title="Di chuyển lên">
+                <i class="fa-solid fa-chevron-up text-[10px]"></i>
+              </button>
+              <button onclick="moveTrack(${idx}, 1)" class="w-6 h-6 rounded bg-slate-800 hover:bg-slate-700 text-slate-400 hover:text-white flex items-center justify-center transition-colors" title="Di chuyển xuống">
+                <i class="fa-solid fa-chevron-down text-[10px]"></i>
+              </button>
+              <button onclick="removeTrack(${idx})" class="w-6 h-6 rounded bg-red-950/80 hover:bg-red-900 text-red-400 flex items-center justify-center transition-colors ml-1" title="Xóa Track">
+                <i class="fa-solid fa-trash-can text-[10px]"></i>
+              </button>
+            </div>
+          </div>
+
+          <div class="grid grid-cols-2 gap-2 text-xs">
+            <div>
+              <label class="block text-[10px] text-slate-500 font-mono mb-0.5">Tên Track (Mã Tiếng Anh):</label>
+              <input type="text" list="trackNameDatalist" value="${escapeHtml(track.name)}" oninput="updateTrackData(${idx}, 'name', this.value)" onchange="saveHistoryItem('trackNames', this.value, defaultHistory.trackNames); updateTrackData(${idx}, 'name', this.value)" class="w-full bg-slate-950 border border-slate-800 rounded px-2.5 py-1.5 text-white font-mono text-xs focus:outline-none focus:border-cyan-500" placeholder="Chọn hoặc nhập tên track...">
+            </div>
+            <div>
+              <label class="block text-[10px] text-slate-500 font-mono mb-0.5">Nhãn / Chú Thích Tiếng Việt:</label>
+              <input type="text" list="trackLabelDatalist" value="${escapeHtml(track.label)}" oninput="updateTrackData(${idx}, 'label', this.value)" onchange="saveHistoryItem('trackLabels', this.value, defaultHistory.trackLabels); updateTrackData(${idx}, 'label', this.value)" class="w-full bg-slate-950 border border-slate-800 rounded px-2.5 py-1.5 text-slate-300 text-xs focus:outline-none focus:border-cyan-500" placeholder="Chọn hoặc nhập nhãn chú thích...">
+            </div>
+          </div>
+
+          <div class="text-xs">
+            <label class="block text-[10px] text-slate-500 font-mono mb-0.5">Mô tả Quy cách Đánh & Tiết tấu:</label>
+            <textarea rows="2" oninput="updateTrackData(${idx}, 'description', this.value)" class="w-full bg-slate-950 border border-slate-800 rounded p-2 text-white font-sans text-xs focus:outline-none focus:border-cyan-500 leading-relaxed">${escapeHtml(track.description)}</textarea>
+          </div>
+        `;
+        tracksContainer.appendChild(card);
+      });
+    }
+
+    function escapeHtml(str) {
+      return (str || "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+    }
+
+    // Main Prompt Generator
+    function generatePromptText() {
+      const timeData = computeTimeMetrics();
+      const role = inputRole.value.trim();
+      const actionDesc = inputActionDesc.value.trim();
+      const sectionType = inputSectionType.value.trim();
+      const toolName = inputToolName.value.trim();
+      const densityRule = inputDensityRule.value.trim();
+      const trackCount = state.tracks.length;
+
+      let promptStr = `Bạn là ${role}. Hãy ${actionDesc} bằng một đoạn ${sectionType} dài ${timeData.barCount} ô nhịp (Từ Ô nhịp ${timeData.start} đến ${timeData.end}, tương ứng với Phách 0.0 đến ${timeData.totalBeats}).\n\n`;
+
+      promptStr += `YÊU CẦU BẮT BUỘC VỀ ĐỘ DÀI TOÀN BỘ:\n\n`;
+      promptStr += `Tất cả ${trackCount} track ĐỀU PHẢI tạo ra các nốt nhạc bao phủ toàn bộ khoảng từ phách 0.0 đến phách ${timeData.totalBeats}, không được dừng lại giữa chừng.\n\n`;
+      promptStr += `Nhịp điệu phải liên tục không đứt đoạn qua các Ô nhịp ${timeData.barListStr}.\n\n`;
+      promptStr += `Nốt/hợp âm cuối cùng của mỗi track phải kéo dài đến hoặc giải kết (resolve) tại phách ${timeData.totalBeats}.\n\n`;
+
+      if (densityRule) {
+        promptStr += `${densityRule}\n\n`;
+      }
+
+      promptStr += `Cấu trúc bắt buộc trả về thông qua công cụ ${toolName} gồm ${trackCount} track:\n\n`;
+
+      state.tracks.forEach((track, i) => {
+        promptStr += `${track.name} (${track.label}): ${track.description.trim()}\n\n`;
+      });
+
+      promptStr += `Đảm bảo mọi track đều chạm tới phách ${timeData.totalBeats}.`;
+
+      promptOutputText.innerText = promptStr;
+    }
+
+    // Dynamic Track Actions
+    window.updateTrackData = function(index, key, val) {
+      state.tracks[index][key] = val;
+      generatePromptText();
+    };
+
+    window.removeTrack = function(index) {
+      if (state.tracks.length <= 1) {
+        showToast("Cần giữ ít nhất 1 Track!", "error");
+        return;
+      }
+      state.tracks.splice(index, 1);
+      renderTrackEditors();
+      generatePromptText();
+    };
+
+    window.moveTrack = function(index, direction) {
+      const newIndex = index + direction;
+      if (newIndex < 0 || newIndex >= state.tracks.length) return;
+      const temp = state.tracks[index];
+      state.tracks[index] = state.tracks[newIndex];
+      state.tracks[newIndex] = temp;
+      renderTrackEditors();
+      generatePromptText();
+    };
+
+    btnAddTrack.addEventListener('click', () => {
+      const newId = `track_${Date.now()}`;
+      state.tracks.push({
+        id: newId,
+        name: `Track ${state.tracks.length + 1}`,
+        label: `Mô tả Track ${state.tracks.length + 1}`,
+        description: `đánh tuyến nốt hòa âm liên tục từ phách 0.0 đến phách 64.0.`
+      });
+      renderTrackEditors();
+      generatePromptText();
+    });
+
+    // Toast Notification System
+    function showToast(msg, type = "success") {
+      const toastMsg = document.getElementById('toastMessage');
+      toastMsg.innerText = msg;
+      
+      if (type === "error") {
+        toastNotification.classList.remove('bg-emerald-600');
+        toastNotification.classList.add('bg-red-600');
+      } else {
+        toastNotification.classList.remove('bg-red-600');
+        toastNotification.classList.add('bg-emerald-600');
+      }
+
+      toastNotification.classList.remove('translate-y-10', 'opacity-0', 'pointer-events-none');
+      setTimeout(() => {
+        toastNotification.classList.add('translate-y-10', 'opacity-0', 'pointer-events-none');
+      }, 2500);
+    }
+
+    // Open Save Preset Modal Event Handler — post data to parent React app
+    btnSavePresetModal.addEventListener('click', () => {
+      const timeData = computeTimeMetrics();
+      const currentPromptText = promptOutputText.innerText.trim();
+
+      const sectionType = inputSectionType.value.trim() || "Building Section";
+      const role = inputRole.value.trim() || "Composer";
+
+      // Auto-infer Category based on Role
+      let category = "Orchestral / Film Score";
+      const roleLower = role.toLowerCase();
+      if (roleLower.includes("piano")) category = "Piano Solo";
+      else if (roleLower.includes("edm") || roleLower.includes("electro")) category = "EDM / Pop";
+      else if (roleLower.includes("jazz")) category = "Jazz & Swing";
+      else if (roleLower.includes("lo-fi") || roleLower.includes("chillhop")) category = "Lo-fi Chillhop";
+
+      // Auto-generate Keyword Tags
+      const keywordList = [
+        sectionType.toLowerCase(),
+        roleLower.split(' ')[0],
+        `${timeData.barCount} bars`
+      ];
+      const keywordsStr = keywordList.filter(Boolean).join(', ');
+
+      // Post data to parent window (React AI PROMPT PRESET MANAGER)
+      window.parent.postMessage({
+        type: 'GENERATOR_PRESET_DATA',
+        name: `${sectionType} (${timeData.barCount} Bars)`,
+        category: category,
+        keywords: keywordsStr,
+        default_bars: timeData.barCount,
+        default_bpm: 120,
+        default_scale: "C Minor",
+        template: currentPromptText
+      }, '*');
+    });
+
+    // Close Modal Event Handlers
+    [btnCloseModalX, btnCloseModalBottom, btnModalBack].forEach(btn => {
+      if (btn) {
+        btn.addEventListener('click', () => {
+          presetManagerModal.classList.add('hidden');
+        });
+      }
+    });
+
+    // Create Structured Preset — replace static numbers with template variables
+    btnCreateStructuredPreset.addEventListener('click', () => {
+      let promptText = presetTemplateTextarea.value;
+      const bars = presetBarsInput.value || "8";
+
+      promptText = promptText
+        .replace(new RegExp(`dài ${bars} ô nhịp`, 'g'), 'dài {{bars}} ô nhịp')
+        .replace(/Từ Ô nhịp \d+ đến \d+/g, 'Từ Ô nhịp {{start_bar}} đến {{end_bar}}')
+        .replace(/Phách 0\.0 đến \d+\.0/g, 'Phách 0.0 đến {{total_beats}}')
+        .replace(/phách \d+\.0/g, 'phách {{total_beats}}');
+
+      presetTemplateTextarea.value = promptText;
+      showToast("Đã chuyển đổi Prompt thành mẫu biến cấu trúc!");
+    });
+
+    // Save Preset Action Handler (Saves to daw_ai_prompt_presets localStorage & dispatches event)
+    btnSavePresetSubmit.addEventListener('click', () => {
+      const name = presetNameInput.value.trim();
+      const category = presetCategorySelect.value;
+      const keywordsRaw = presetKeywordsInput.value.trim();
+      const defaultBars = parseInt(presetBarsInput.value) || 8;
+      const defaultBpm = parseInt(presetBpmInput.value) || 120;
+      const defaultScale = presetScaleInput.value.trim() || "C Minor";
+      const template = presetTemplateTextarea.value.trim();
+
+      if (!name) {
+        showToast("Vui lòng nhập Tên Preset!", "error");
+        presetNameInput.focus();
+        return;
+      }
+
+      if (!template) {
+        showToast("Nội dung System Prompt không được trống!", "error");
+        return;
+      }
+
+      const keywords = keywordsRaw ? keywordsRaw.split(',').map(k => k.trim()).filter(Boolean) : [name.toLowerCase()];
+
+      const newPresetObj = {
+        id: `preset_${Date.now()}`,
+        name: name,
+        category: category,
+        keywords: keywords,
+        default_bars: defaultBars,
+        default_bpm: defaultBpm,
+        default_scale: defaultScale,
+        system_instruction_template: template,
+        is_user_defined: true,
+        created_at: new Date().toISOString()
+      };
+
+      // Read existing saved presets list from localStorage
+      let savedPresets = [];
+      try {
+        const stored = localStorage.getItem('daw_ai_prompt_presets');
+        savedPresets = stored ? JSON.parse(stored) : [];
+      } catch (e) {
+        savedPresets = [];
+      }
+
+      savedPresets.unshift(newPresetObj);
+
+      try {
+        localStorage.setItem('daw_ai_prompt_presets', JSON.stringify(savedPresets));
+        // Dispatch Custom Event so parent window updates preset list instantly
+        window.dispatchEvent(new CustomEvent('AI_PRESET_SAVED', { detail: newPresetObj }));
+        showToast(`Đã lưu Preset "${name}" thành công!`);
+        presetManagerModal.classList.add('hidden');
+      } catch (e) {
+        showToast("Lỗi khi lưu vào bộ nhớ trình duyệt!", "error");
+      }
+    });
+
+    // Copy Prompt Button
+    btnCopyPrompt.addEventListener('click', () => {
+      // Save current input values to history when copying
+      saveHistoryItem('roles', inputRole.value, defaultHistory.roles);
+      saveHistoryItem('actions', inputActionDesc.value, defaultHistory.actions);
+      saveHistoryItem('sectionTypes', inputSectionType.value, defaultHistory.sectionTypes);
+
+      // Save tracks history
+      state.tracks.forEach(track => {
+        saveHistoryItem('trackNames', track.name, defaultHistory.trackNames);
+        saveHistoryItem('trackLabels', track.label, defaultHistory.trackLabels);
+      });
+
+      const textToCopy = promptOutputText.innerText;
+      
+      // Fallback copy execCommand for iframe compatibility
+      const textarea = document.createElement('textarea');
+      textarea.value = textToCopy;
+      document.body.appendChild(textarea);
+      textarea.select();
+      try {
+        document.execCommand('copy');
+        showToast("Đã sao chép câu Prompt thành công!");
+      } catch (err) {
+        showToast("Lỗi khi sao chép!", "error");
+      }
+      document.body.removeChild(textarea);
+    });
+
+    // Reset Default Piano Preset
+    btnLoadDefaultPreset.addEventListener('click', () => {
+      inputRole.value = "nghệ sĩ piano chuyên nghiệp và là nhà soạn nhạc phim";
+      inputActionDesc.value = "tiếp tục bản nhạc piano đầy cảm xúc này";
+      inputSectionType.value = "Cao trào (Build-Up) kịch tính";
+      inputToolName.value = "generate_multitrack_midi";
+      inputStartBar.value = "9";
+      inputEndBar.value = "16";
+      selectBeatsPerBar.value = "4";
+      inputDensityRule.value = "Hãy giữ mật độ nốt hiệu quả (chủ yếu là nốt đen và các đoạn rải hợp âm nốt móc đơn đều đặn, tránh các chuỗi nốt móc đôi/móc ba quá dày đặc) để tránh bị quá giới hạn thời gian xuất dữ liệu (token timeout).";
+
+      state.tracks = [
+        {
+          id: "track_1",
+          name: "Piano Bass & Octaves",
+          label: "Tiếng Bass & Quãng 8 Piano",
+          description: "đánh các xung bass trầm nốt đen đều đặn (trong dải C1-C3) liên tục trên mỗi phách từ phách 0.0 đến phách 64.0 (tổng cộng 64 nốt đen)."
+        },
+        {
+          id: "track_2",
+          name: "Piano Accompaniment",
+          label: "Tiếng Đệm Piano",
+          description: "đánh các đoạn rải hợp âm (broken chord arpeggios) nốt móc đơn có nhịp điệu ở âm vực trung (dải C3-C4), lấp đầy liên tục toàn bộ 8 ô nhịp từ phách 0.0 đến phách 64.0."
+        },
+        {
+          id: "track_3",
+          name: "Piano Melody - Right Hand",
+          label: "Giai điệu Piano - Tay phải",
+          description: "đánh một tuyến giai điệu đi lên ở âm vực cao (dải C4-C6) sử dụng nốt trắng và nốt tròn trải dài từ Ô nhịp 9 đến 16, kết thúc bằng một hợp âm chủ (tonic chord) ngân dài được giữ cho đến phách 64.0."
+        }
+      ];
+
+      renderTrackEditors();
+      generatePromptText();
+      showToast("Đã nạp lại Mẫu Prompt Piano!");
+    });
+
+    // Export Preset JSON
+    btnExportJSON.addEventListener('click', () => {
+      const exportData = {
+        role: inputRole.value,
+        actionDesc: inputActionDesc.value,
+        sectionType: inputSectionType.value,
+        startBar: parseInt(inputStartBar.value),
+        endBar: parseInt(inputEndBar.value),
+        beatsPerBar: parseInt(selectBeatsPerBar.value),
+        densityRule: inputDensityRule.value,
+        toolName: inputToolName.value,
+        tracks: state.tracks
+      };
+
+      const dataStr = "data:text/json;charset=utf-8," + encodeURIComponent(JSON.stringify(exportData, null, 2));
+      const downloadAnchor = document.createElement('a');
+      downloadAnchor.setAttribute("href", dataStr);
+      downloadAnchor.setAttribute("download", `midi_prompt_preset_${Date.now()}.json`);
+      document.body.appendChild(downloadAnchor);
+      downloadAnchor.click();
+      downloadAnchor.remove();
+      showToast("Đã xuất tệp JSON Preset!");
+    });
+
+    // Import Preset JSON
+    jsonFileInput.addEventListener('change', (e) => {
+      const file = e.target.files[0];
+      if (!file) return;
+
+      const reader = new FileReader();
+      reader.onload = (event) => {
+        try {
+          const imported = JSON.parse(event.target.result);
+          if (imported.role) inputRole.value = imported.role;
+          if (imported.actionDesc) inputActionDesc.value = imported.actionDesc;
+          if (imported.sectionType) inputSectionType.value = imported.sectionType;
+          if (imported.startBar) inputStartBar.value = imported.startBar;
+          if (imported.endBar) inputEndBar.value = imported.endBar;
+          if (imported.beatsPerBar) selectBeatsPerBar.value = imported.beatsPerBar;
+          if (imported.densityRule !== undefined) inputDensityRule.value = imported.densityRule;
+          if (imported.toolName) inputToolName.value = imported.toolName;
+          if (Array.isArray(imported.tracks)) state.tracks = imported.tracks;
+
+          renderTrackEditors();
+          generatePromptText();
+          showToast("Đã nạp Preset từ tệp JSON thành công!");
+        } catch (err) {
+          showToast("Tệp JSON không hợp lệ!", "error");
+        }
+      };
+      reader.readAsText(file);
+    });
+
+    // Attach input listeners
+    [inputRole, inputActionDesc, inputSectionType, inputToolName, inputStartBar, inputEndBar, selectBeatsPerBar, inputDensityRule].forEach(elem => {
+      elem.addEventListener('input', generatePromptText);
+    });
+
+    // Initial Render
+    window.addEventListener('load', () => {
+      initHistoryDatalists();
+      renderTrackEditors();
+      generatePromptText();
+    });
+  </script>
+</body>
+</html>

md/50_APPLY_GENERATOR.md

@@ -0,0 +1,346 @@
+# TECHNICAL SPECIFICATION: AUTOMATED DATA TRANSFER FROM MIDI PROMPT GENERATOR TO AI PRESET MANAGER
+
+This document details the software implementation plan to automatically extract calculated parameters (Bars, BPM, Category, Keywords, Prompt Content) and auto-populate the AI Prompt Preset Manager form whenever a user clicks the "Save as Preset" button on the MIDI AI Prompt Generator tool, adhering strictly to the designated interface layout.
+
+---
+
+## 1. TECHNICAL GOALS
+
+* **Zero Re-typing:** Eliminates manual copy-pasting of generated prompt text or re-entering parameters such as Bars, Role, and Category.
+* **Smart Data Mapping:**
+* Auto-suggests a **Preset Name** based on Section Type and Bar Count.
+* Auto-extracts **Trigger Keywords** from Role, Section Type, and Action Descriptions.
+* Auto-calculates **Default Bars** using the formula $(\text{EndBar} - \text{StartBar} + 1)$.
+* Overwrites the complete generated prompt text directly into the **SYSTEM PROMPT TEMPLATE** area.
+
+
+* **Structured Preset Generation ("Create Structured Preset" Green Button):** Enables converting static prompt text into a structured variable template containing dynamic placeholders (e.g., `{{start_bar}}`, `{{end_bar}}`, `{{total_beats}}`).
+
+---
+
+## 2. DATA MAPPING MATRIX
+
+Upon clicking "Save as Preset", the system reads the active State from the Prompt Generator and maps it to the Modal fields:
+
+| AI Prompt Preset Manager Field | Source Data from Prompt Generator | Processing Rules / Logic | Example Auto-Populated Data |
+| --- | --- | --- | --- |
+| **PRESET NAME** | `inputSectionType` + `barCount` | `${sectionType} (${barCount} Bars)` | `"Dramatic Build-Up (8 Bars)"` |
+| **CATEGORY** | `inputRole` | Evaluates role keywords to assign category (Piano, Orchestral, EDM, Cinematic, etc.) | `"Piano Solo"` or `"Orchestral / Film Score"` |
+| **TRIGGER KEYWORDS** | `sectionType` + `role` + `trackLabels` | Extracts key nouns, formatted as a comma-separated string | `"build-up, dramatic, piano solo, 8 bars"` |
+| **DEFAULT BARS** | `inputStartBar` & `inputEndBar` | $\max(1, (\text{EndBar} - \text{StartBar} + 1))$ | `8` |
+| **DEFAULT BPM** | Form / State Context | Inherits active project BPM or defaults to 120 | `120` |
+| **DEFAULT SCALE** | Form / State Context | Inherits active project key signature or defaults to C Minor | `"C Minor"` |
+| **SYSTEM PROMPT TEMPLATE** | `promptOutputText.innerText` | Extracts the compiled output text directly from the Live Preview component | *(Full generated prompt text)* |
+
+---
+
+## 3. DATA FLOW LIFECYCLE
+
+```text
+[ USER GENERATES PROMPT ON GENERATOR FORM ]
+                      │
+                      ▼
+[ CLICK BUTTON: "Save as Preset" ]
+                      │
+                      ├─► 1. Call `computeTimeMetrics()` (Extract StartBar, EndBar, TotalBeats)
+                      ├─► 2. Extract `generatePromptText()`
+                      ├─► 3. Invoke `autoFillPresetModal(stateData)`
+                      │
+                      ▼
+[ POPUP MODAL: "AI PROMPT PRESET MANAGER" OPENS ]
+  - Preset Name       <-- Auto-populated
+  - Category          <-- Auto-selected via dropdown
+  - Trigger Keywords  <-- Auto-generated tag string
+  - Bars / BPM        <-- Auto-populated numbers
+  - System Prompt     <-- Full prompt text inserted
+                      │
+                      ├──► [ CLICK "Create Structured Preset" (Green Button) ]
+                      │      └─► Converts static text to template variable placeholders (`{{total_beats}}`)
+                      │
+                      └──► [ CLICK "Save Preset" (Purple Button) ]
+                             └─► Saves JSON object to `localStorage('daw_ai_prompt_presets')` & closes Modal
+
+```
+
+---
+
+## 4. STEP-BY-STEP IMPLEMENTATION PLAN
+
+### Step 1: Update Modal UI
+
+Position the green **"Create Structured Preset"** button at the bottom-left of the modal action bar (adjacent to the Back, Save Preset, and Close button group).
+
+### Step 2: Build `autoFillPresetModal()` Function
+
+Implement a JavaScript function responsible for parsing active form control values and injecting them into the target modal input elements when triggered.
+
+### Step 3: Implement "Create Structured Preset" Logic (Green Button Feature)
+
+Program the handler to parse static numeric values within the prompt text (e.g., 8 bars, beat 64.0, Bars 9 to 16) and replace them with dynamic template placeholders (`{{bars}}`, `{{total_beats}}`, `{{start_bar}}`, `{{end_bar}}`). This allows saved presets to adapt dynamically to variable bar lengths when reused.
+
+### Step 4: LocalStorage & Event Bus Integration
+
+Save the compiled preset object to `localStorage` under the key `daw_ai_prompt_presets` and dispatch a `PRESET_CREATED` CustomEvent so that the AI Copilot Chat Bar updates its preset options instantly without requiring a page refresh.
+
+---
+
+## 5. CODE IMPLEMENTATION SNIPPETS
+
+### 5.1 Modal HTML Markup
+
+```html
+<!-- MODAL: AI PROMPT PRESET MANAGER -->
+<div id="presetManagerModal" class="fixed inset-0 bg-black/80 backdrop-blur-md z-50 flex items-center justify-center hidden p-4">
+  <div class="w-full max-w-3xl bg-[#13141a] border border-slate-800 rounded-2xl shadow-2xl p-6 space-y-4 text-slate-200 relative overflow-hidden">
+    
+    <!-- Header -->
+    <div class="flex items-center justify-between border-b border-slate-800/80 pb-3">
+      <h2 class="text-sm font-bold tracking-widest text-transparent bg-clip-text bg-gradient-to-r from-purple-400 via-pink-400 to-indigo-400 font-mono uppercase">
+        AI PROMPT PRESET MANAGER
+      </h2>
+      <button id="btnCloseModalX" class="w-7 h-7 rounded-lg bg-slate-800 hover:bg-slate-700 text-slate-400 hover:text-white flex items-center justify-center transition-colors">
+        <i class="fa-solid fa-xmark"></i>
+      </button>
+    </div>
+
+    <!-- Section Sub-Title -->
+    <div class="text-xs font-bold text-slate-300 uppercase tracking-wider font-mono flex items-center gap-2">
+      <i class="fa-solid fa-wand-magic-sparkles text-purple-400"></i> CREATE NEW PRESET
+    </div>
+
+    <!-- Form Input Grid -->
+    <div class="space-y-3 text-xs">
+      
+      <!-- Row 1: Name & Category -->
+      <div class="grid grid-cols-2 gap-3">
+        <div>
+          <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">PRESET NAME</label>
+          <input type="text" id="presetNameInput" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white focus:outline-none focus:border-purple-500 font-sans" placeholder="Enter preset name...">
+        </div>
+        <div>
+          <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">CATEGORY</label>
+          <select id="presetCategorySelect" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white focus:outline-none focus:border-purple-500 font-sans">
+            <option value="Orchestral / Film Score">Orchestral / Film Score</option>
+            <option value="Piano Solo">Piano Solo</option>
+            <option value="EDM / Pop">EDM / Pop</option>
+            <option value="Cinematic">Cinematic</option>
+            <option value="Jazz & Swing">Jazz & Swing</option>
+            <option value="Lo-fi Chillhop">Lo-fi Chillhop</option>
+          </select>
+        </div>
+      </div>
+
+      <!-- Row 2: Trigger Keywords -->
+      <div>
+        <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">TRIGGER KEYWORDS (COMMA-SEPARATED)</label>
+        <input type="text" id="presetKeywordsInput" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white focus:outline-none focus:border-purple-500 font-sans" placeholder="e.g. epic orchestra, dramatic, film score">
+      </div>
+
+      <!-- Row 3: Bars, BPM, Scale -->
+      <div class="grid grid-cols-3 gap-3">
+        <div>
+          <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">DEFAULT BARS</label>
+          <input type="number" id="presetBarsInput" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white font-mono focus:outline-none focus:border-purple-500">
+        </div>
+        <div>
+          <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">DEFAULT BPM</label>
+          <input type="number" id="presetBpmInput" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white font-mono focus:outline-none focus:border-purple-500">
+        </div>
+        <div>
+          <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">DEFAULT SCALE</label>
+          <input type="text" id="presetScaleInput" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg px-3 py-2 text-white font-mono focus:outline-none focus:border-purple-500">
+        </div>
+      </div>
+
+      <!-- Row 4: Template Textarea -->
+      <div>
+        <label class="block text-[10px] font-bold text-slate-400 uppercase tracking-wider mb-1">SYSTEM PROMPT TEMPLATE</label>
+        <textarea id="presetTemplateTextarea" rows="6" class="w-full bg-[#1a1c23] border border-slate-800 rounded-lg p-3 text-white font-mono text-xs focus:outline-none focus:border-purple-500 leading-relaxed custom-scrollbar"></textarea>
+      </div>
+
+    </div>
+
+    <!-- Bottom Action Row -->
+    <div class="space-y-3 pt-2 border-t border-slate-800/80">
+      <div class="flex items-center justify-between">
+        <!-- Green Button: Create Structured Preset -->
+        <button id="btnCreateStructuredPreset" class="px-4 py-2 bg-emerald-700 hover:bg-emerald-600 text-white rounded-lg text-xs font-bold transition-all shadow-md flex items-center gap-1.5">
+          Create Structured Preset
+        </button>
+
+        <!-- Right Button Group: Back + Save Preset -->
+        <div class="flex items-center gap-2">
+          <button id="btnModalBack" class="px-4 py-2 bg-[#252836] hover:bg-slate-700 text-slate-300 rounded-lg text-xs font-semibold transition-colors">
+            Back
+          </button>
+          <button id="btnSavePresetSubmit" class="px-5 py-2 bg-purple-600 hover:bg-purple-500 text-white rounded-lg text-xs font-bold transition-all shadow-lg shadow-purple-950/80 flex items-center gap-1.5">
+            Save Preset
+          </button>
+        </div>
+      </div>
+
+      <!-- Bottom Close Button -->
+      <div class="flex justify-end">
+        <button id="btnCloseModalBottom" class="px-4 py-1.5 bg-[#1f222e] hover:bg-slate-700 text-slate-300 rounded-lg text-xs font-semibold transition-colors">
+          Close
+        </button>
+      </div>
+    </div>
+
+  </div>
+</div>
+
+```
+
+---
+
+### 5.2 Auto-Populate Logic (`autoFillPresetModal`)
+
+```javascript
+// Function: Auto-populate Modal fields when "Save as Preset" is clicked
+function handleOpenSavePresetModal() {
+  // 1. Calculate time metrics from the Form Engine
+  const timeData = computeTimeMetrics(); // returns { barCount, totalBeats, start, end }
+  const currentGeneratedPrompt = promptOutputText.innerText.trim();
+
+  // 2. Read values from form controls
+  const sectionType = inputSectionType.value.trim() || "Building Section";
+  const role = inputRole.value.trim() || "Composer";
+  const actionDesc = inputActionDesc.value.trim();
+
+  // 3. Auto-infer Category based on Role or Section
+  let category = "Orchestral / Film Score";
+  const roleLower = role.toLowerCase();
+  if (roleLower.includes("piano")) category = "Piano Solo";
+  else if (roleLower.includes("edm") || roleLower.includes("electro")) category = "EDM / Pop";
+  else if (roleLower.includes("jazz")) category = "Jazz & Swing";
+  else if (roleLower.includes("lo-fi") || roleLower.includes("chillhop")) category = "Lo-fi Chillhop";
+
+  // 4. Auto-generate Keyword Tags
+  const keywordList = [
+    sectionType.toLowerCase(),
+    roleLower.split(' ')[0],
+    `${timeData.barCount} bars`
+  ];
+  const keywordsStr = keywordList.filter(Boolean).join(', ');
+
+  // 5. Populate Form Fields
+  presetNameInput.value = `${sectionType} (${timeData.barCount} Bars)`;
+  presetCategorySelect.value = category;
+  presetKeywordsInput.value = keywordsStr;
+  presetBarsInput.value = timeData.barCount;
+  presetBpmInput.value = 120; // Default BPM or read from session context
+  presetScaleInput.value = "C Minor";
+  presetTemplateTextarea.value = currentGeneratedPrompt;
+
+  // 6. Display Modal
+  presetManagerModal.classList.remove('hidden');
+}
+
+// Event Listener for the main button
+btnSavePresetModal.addEventListener('click', handleOpenSavePresetModal);
+
+```
+
+---
+
+### 5.3 Structured Preset Variable Replacement ("Create Structured Preset")
+
+```javascript
+// Function: Converts static numbers in prompt into dynamic placeholders
+btnCreateStructuredPreset.addEventListener('click', () => {
+  let promptText = presetTemplateTextarea.value;
+  const bars = presetBarsInput.value || "8";
+
+  // Replace specific numbers with template variables
+  promptText = promptText
+    .replace(new RegExp(`dài ${bars} ô nhịp`, 'g'), 'dài {{bars}} ô nhịp')
+    .replace(/Từ Ô nhịp \d+ đến \d+/g, 'Từ Ô nhịp {{start_bar}} đến {{end_bar}}')
+    .replace(/Phách 0\.0 đến \d+\.0/g, 'Phách 0.0 đến {{total_beats}}')
+    .replace(/phách \d+\.0/g, 'phách {{total_beats}}');
+
+  presetTemplateTextarea.value = promptText;
+  showToast("Converted Prompt to Structured Variable Template!");
+});
+
+```
+
+---
+
+### 5.4 Save Preset Handler (`localStorage` & Event Dispatch)
+
+```javascript
+btnSavePresetSubmit.addEventListener('click', () => {
+  const name = presetNameInput.value.trim();
+  const category = presetCategorySelect.value;
+  const keywordsRaw = presetKeywordsInput.value.trim();
+  const defaultBars = parseInt(presetBarsInput.value) || 8;
+  const defaultBpm = parseInt(presetBpmInput.value) || 120;
+  const defaultScale = presetScaleInput.value.trim() || "C Minor";
+  const template = presetTemplateTextarea.value.trim();
+
+  if (!name) {
+    showToast("Please enter a Preset Name!", "error");
+    presetNameInput.focus();
+    return;
+  }
+
+  if (!template) {
+    showToast("System Prompt content cannot be empty!", "error");
+    return;
+  }
+
+  const newPresetObj = {
+    id: `preset_${Date.now()}`,
+    name: name,
+    category: category,
+    keywords: keywordsRaw ? keywordsRaw.split(',').map(k => k.trim()) : [name.toLowerCase()],
+    default_bars: defaultBars,
+    default_bpm: defaultBpm,
+    default_scale: defaultScale,
+    system_instruction_template: template,
+    is_user_defined: true,
+    created_at: new Date().toISOString()
+  };
+
+  // Read existing presets and prepend new one
+  let savedPresets = [];
+  try {
+    const stored = localStorage.getItem('daw_ai_prompt_presets');
+    savedPresets = stored ? JSON.parse(stored) : [];
+  } catch (e) {
+    savedPresets = [];
+  }
+
+  savedPresets.unshift(newPresetObj);
+  localStorage.setItem('daw_ai_prompt_presets', JSON.stringify(savedPresets));
+
+  // Dispatch Custom Event so Copilot Chat UI updates dynamically
+  window.dispatchEvent(new CustomEvent('AI_PRESET_SAVED', { detail: newPresetObj }));
+
+  showToast(`Preset "${name}" saved successfully!`);
+  presetManagerModal.classList.add('hidden');
+});
+
+```
+
+---
+
+## 6. OPERATIONAL VERIFICATION CHECKLIST
+
+* [ ] Open Form Generator and set parameters (e.g., Bars 9 to 16, Role: Pianist).
+* [ ] Click "Save as Preset":
+* Modal opens.
+* **PRESET NAME** displays: `Dramatic Build-Up (8 Bars)`.
+* **CATEGORY** selects: `Piano Solo`.
+* **DEFAULT BARS** populates: `8`.
+* **SYSTEM PROMPT TEMPLATE** contains the generated prompt text.
+
+
+* [ ] Test the "Create Structured Preset" green button:
+* Click button $\rightarrow$ values such as 8 bars or beat 64.0 are converted to variables like `{{bars}}` and `{{total_beats}}`.
+
+
+* [ ] Click "Save Preset" (Purple Button):
+* Toast notification confirms save.
+* `localStorage.getItem('daw_ai_prompt_presets')` contains the new preset object at the beginning of the array.

md/51_MEDIA_EXPLORER.md

@@ -0,0 +1,349 @@
+# DETAILED SPECIFICATION FOR DAW MEDIA EXPLORER PANEL INTERFACE & HTML5 SOURCE CODE
+
+This document details the design structure, features, and executable HTML5 source code for a general-purpose Media Explorer Panel interface styled after the REAPER DAW.
+
+---
+
+## I. DETAILED INTERFACE REGIONS
+
+The interface is divided vertically into 3 primary functional regions, arranged from top to bottom:
+
+### 1. Top Navigation Toolbar
+
+* **Left Navigation Button Group:** **←** (Back), **→** (Forward), **↑** (Up to Parent Directory), **↻** (Refresh).
+* **Directory Address Bar:** Displays the current folder path with a drop-down menu for quick-access path selection.
+* **Filter / Search Box:** Input field supporting quick file filtering and keyword searching.
+* **View Mode Button:** Toggle button for switching file display layouts (*Details* / *List* view).
+
+### 2. Middle Split Panel (Directory Tree + File List)
+
+* **Left Directory Tree View:**
+* Hierarchical tree structure displaying project directories, system shortcuts, drives, and audio sample library folders.
+* Supports expand/collapse toggle buttons and highlighted background states indicating the actively selected folder.
+
+
+* **Right File List Table:**
+* Displays audio and MIDI files with standard category icons.
+* Highlights the currently selected file with a prominent blue row background.
+
+
+
+### 3. Bottom Preview & Transport Panel
+
+* **Transport Control Bar & Playback Parameters:**
+* **Transport Buttons:** **■** (Stop), **▶** (Play), **❚❚** (Pause), **↻** (Loop/Repeat), **⚡ Auto-Play** (Automatically previews files upon selection).
+* **Parameter Controls:** Pitch adjustment (Pitch matching), Rate (Playback speed factor), Volume Slider (Gain adjustment in dB).
+* **Media Type Badge:** Label displaying file format classification (*MIDI* / *Audio*).
+
+
+* **Visualizer Canvas Display & Metadata:**
+* **Visualizer Canvas (Left):** Dark display area rendering an overview Piano Roll note grid (for MIDI files) or waveform display (for Audio files), integrated with a timeline/bar ruler and white Playhead cursor.
+* **Metadata Text Box (Right):** Information pane displaying detailed file parameters (MIDI event count, duration, sample rate / resolution).
+
+
+* **Footer Status Bar:**
+* Displays current playback timestamp vs. total file length.
+* Name of the currently selected/playing file.
+* Tempo metadata (BPM) and playback rate scale factor.
+
+
+
+---
+
+## II. EXECUTABLE HTML5 & TAILWIND CSS SOURCE CODE
+
+Below is the complete HTML5 source code integrating Web Audio API synthesis, a Canvas visualizer, and real-time interactive file selection and audio preview playback:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>DAW Media Explorer Panel Component</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet">
+  <style>
+    body { font-family: 'Inter', sans-serif; user-select: none; }
+    .font-mono { font-family: 'JetBrains Mono', monospace; }
+
+    /* REAPER Classic Panel Style */
+    .reaper-panel {
+      background: #c0c0c0;
+      border: 2px solid #ffffff;
+      border-right-color: #808080;
+      border-bottom-color: #808080;
+    }
+    .reaper-inset {
+      background: #ffffff;
+      border: 1px solid #808080;
+      box-shadow: inset 1px 1px 2px rgba(0,0,0,0.3);
+    }
+    .reaper-dark-inset {
+      background: #181818;
+      border: 1px solid #3a3a3a;
+      box-shadow: inset 1px 1px 3px rgba(0,0,0,0.8);
+    }
+    .file-row-selected {
+      background-color: #3399ff !important;
+      color: #ffffff !important;
+    }
+    .file-row-selected .file-icon { color: #ffffff !important; }
+
+    /* Scrollbar */
+    ::-webkit-scrollbar { width: 12px; height: 12px; }
+    ::-webkit-scrollbar-track { background: #e0e0e0; border-left: 1px solid #a0a0a0; }
+    ::-webkit-scrollbar-thumb { background: #b0b0b0; border: 1px solid #ffffff; border-right-color: #707070; border-bottom-color: #707070; }
+    ::-webkit-scrollbar-thumb:hover { background: #909090; }
+
+    /* Volume Slider */
+    input[type=range].fader-slider {
+      appearance: none; -webkit-appearance: none;
+      background: #111; height: 6px; border-radius: 3px; border: 1px solid #555;
+    }
+    input[type=range].fader-slider::-webkit-slider-thumb {
+      -webkit-appearance: none; height: 16px; width: 12px;
+      background: linear-gradient(180deg, #e2e8f0 0%, #64748b 50%, #1e293b 100%);
+      border: 1px solid #000; border-radius: 2px; box-shadow: 0 2px 4px rgba(0,0,0,0.5); cursor: pointer;
+    }
+  </style>
+</head>
+<body class="bg-slate-950 text-slate-900 h-screen flex items-center justify-center p-2 overflow-hidden">
+
+  <!-- MEDIA EXPLORER PANEL CONTAINER -->
+  <div class="w-full max-w-4xl h-[420px] flex flex-col reaper-panel text-slate-900 overflow-hidden shadow-2xl relative">
+    
+    <!-- 1. TOP NAVIGATION TOOLBAR -->
+    <div class="h-8 bg-[#d4d0c8] border-b border-[#808080] px-2 flex items-center justify-between text-xs shrink-0">
+      <div class="flex items-center gap-1 flex-1 mr-2">
+        <button class="w-5 h-5 bg-[#e0e0e0] hover:bg-[#ffffff] border border-[#707070] rounded-sm flex items-center justify-center text-[10px]" title="Back">
+          <i class="fa-solid fa-arrow-left"></i>
+        </button>
+        <button class="w-5 h-5 bg-[#e0e0e0] hover:bg-[#ffffff] border border-[#707070] rounded-sm flex items-center justify-center text-[10px]" title="Forward">
+          <i class="fa-solid fa-arrow-right"></i>
+        </button>
+        <button class="w-5 h-5 bg-[#e0e0e0] hover:bg-[#ffffff] border border-[#707070] rounded-sm flex items-center justify-center text-[10px]" title="Up Directory">
+          <i class="fa-solid fa-arrow-up"></i>
+        </button>
+        <button class="w-5 h-5 bg-[#e0e0e0] hover:bg-[#ffffff] border border-[#707070] rounded-sm flex items-center justify-center text-[10px]" title="Refresh">
+          <i class="fa-solid fa-rotate-right"></i>
+        </button>
+
+        <div class="flex-1 flex items-center reaper-inset h-5 px-1 bg-white">
+          <i class="fa-solid fa-folder-open text-[#d9a752] text-[11px] mr-1.5"></i>
+          <input type="text" id="addressBarInput" value="Root:\Media Library" class="w-full text-xs outline-none bg-transparent font-sans text-slate-800" readonly>
+          <i class="fa-solid fa-caret-down text-slate-600 text-[10px] ml-1"></i>
+        </div>
+      </div>
+
+      <div class="flex items-center gap-2">
+        <div class="flex items-center reaper-inset h-5 px-1 bg-white w-40">
+          <input type="text" placeholder="Filter/Search..." class="w-full text-xs outline-none bg-transparent font-sans text-slate-800">
+          <i class="fa-solid fa-caret-down text-slate-600 text-[10px] ml-1"></i>
+        </div>
+        <button class="px-2 py-0.5 bg-[#e0e0e0] hover:bg-[#ffffff] border border-[#707070] rounded-sm text-[11px] flex items-center gap-1 font-semibold">
+          <span>Details</span> <i class="fa-solid fa-caret-down text-[9px]"></i>
+        </button>
+      </div>
+    </div>
+
+    <!-- 2. MIDDLE SPLIT VIEW (DIRECTORY TREE + FILE LIST) -->
+    <div class="flex-1 flex overflow-hidden">
+      
+      <!-- DIRECTORY TREE (LEFT) -->
+      <div class="w-60 reaper-inset m-1 mr-0 overflow-y-auto p-1 text-xs select-none bg-white">
+        <div class="space-y-0.5 font-sans">
+          <div class="flex items-center gap-1 px-1 py-0.5 hover:bg-slate-200 text-slate-700"><span class="w-3"></span> &lt;Track Templates&gt;</div>
+          <div class="flex items-center gap-1 px-1 py-0.5 hover:bg-slate-200 text-slate-700"><span class="w-3"></span> &lt;Project Directory&gt;</div>
+          <div class="flex items-center gap-1 px-1 py-0.5 hover:bg-slate-200 text-slate-700"><i class="fa-solid fa-plus text-[9px] text-slate-500"></i> My Computer</div>
+
+          <!-- Selected Folder -->
+          <div id="folderMidi" class="flex items-center gap-1 px-1 py-0.5 hover:bg-blue-100 cursor-pointer font-semibold text-slate-900 bg-slate-300 rounded-sm">
+            <i class="fa-solid fa-minus text-[9px] text-slate-600"></i>
+            <i class="fa-solid fa-folder-open text-[#d9a752]"></i> Media Library
+          </div>
+
+          <div class="pl-3 space-y-0.5">
+            <div class="flex items-center gap-1 px-1 py-0.5 hover:bg-slate-200 cursor-pointer text-slate-800">
+              <i class="fa-solid fa-plus text-[9px] text-slate-500"></i> <i class="fa-solid fa-folder text-[#d9a752]"></i> Sound Effects
+            </div>
+            <div id="folderDigitalJuice" class="flex items-center gap-1 px-1 py-0.5 hover:bg-blue-100 cursor-pointer text-slate-800 pl-4">
+              <i class="fa-solid fa-folder text-[#d9a752]"></i> MIDI Collections
+            </div>
+          </div>
+
+          <div class="flex items-center gap-1 px-1 py-0.5 hover:bg-slate-200 text-slate-700"><i class="fa-solid fa-plus text-[9px] text-slate-500"></i> Desktop</div>
+          <div class="flex items-center gap-1 px-1 py-0.5 hover:bg-slate-200 text-slate-700"><i class="fa-solid fa-plus text-[9px] text-slate-500"></i> My Documents</div>
+        </div>
+      </div>
+
+      <!-- FILE LIST TABLE (RIGHT) -->
+      <div class="flex-1 reaper-inset m-1 overflow-y-auto relative bg-white">
+        <table class="w-full text-xs text-left border-collapse">
+          <thead class="sticky top-0 bg-[#e0e0e0] border-b border-[#a0a0a0] text-slate-800 font-semibold select-none shadow-sm z-10">
+            <tr><th class="py-1 px-2 border-r border-[#b0b0b0]">File</th></tr>
+          </thead>
+          <tbody id="fileListTbody" class="font-sans text-slate-800">
+            <!-- Dynamic File Rows -->
+          </tbody>
+        </table>
+      </div>
+
+    </div>
+
+    <!-- 3. BOTTOM PREVIEW CONTROL BAR & VISUALIZER CANVAS -->
+    <div class="h-32 bg-[#d4d0c8] border-t border-[#808080] p-1.5 flex flex-col justify-between text-xs shrink-0 select-none">
+      
+      <!-- CONTROLS ROW -->
+      <div class="flex items-center justify-between gap-2">
+        <div class="flex items-center gap-1">
+          <button id="btnStop" class="w-6 h-6 bg-[#e0e0e0] hover:bg-[#ffffff] border border-[#707070] rounded-sm flex items-center justify-center text-slate-800"><i class="fa-solid fa-square text-[10px]"></i></button>
+          <button id="btnPlay" class="w-6 h-6 bg-[#e0e0e0] hover:bg-[#ffffff] border border-[#707070] rounded-sm flex items-center justify-center text-emerald-700 font-bold"><i class="fa-solid fa-play text-xs"></i></button>
+          <button id="btnPause" class="w-6 h-6 bg-[#e0e0e0] hover:bg-[#ffffff] border border-[#707070] rounded-sm flex items-center justify-center text-amber-700"><i class="fa-solid fa-pause text-xs"></i></button>
+          <button id="btnLoop" class="w-6 h-6 bg-[#e0e0e0] hover:bg-[#ffffff] border border-[#707070] rounded-sm flex items-center justify-center text-slate-700"><i class="fa-solid fa-rotate-right text-xs"></i></button>
+          <button id="btnAutoPlay" class="h-6 px-2 bg-gradient-to-r from-cyan-600 to-emerald-600 text-white border border-slate-700 rounded-sm font-bold text-[10px] flex items-center gap-1 shadow-sm">
+            <i class="fa-solid fa-bolt text-[9px]"></i> <span>Auto-Play</span>
+          </button>
+        </div>
+
+        <div class="flex items-center gap-3 font-mono text-[11px]">
+          <div class="flex items-center gap-1">
+            <span>Pitch:</span>
+            <div class="reaper-inset px-1 bg-white h-5 flex items-center w-14">
+              <input type="number" value="0.00" step="0.5" class="w-full text-xs text-right outline-none bg-transparent">
+            </div>
+          </div>
+          <div class="flex items-center gap-1">
+            <span>Rate:</span>
+            <div class="reaper-inset px-1 bg-white h-5 flex items-center w-12">
+              <input type="number" value="1.0" step="0.1" class="w-full text-xs text-right outline-none bg-transparent">
+            </div>
+          </div>
+        </div>
+
+        <div class="flex items-center gap-2">
+          <span class="font-sans text-slate-700">Volume:</span>
+          <input id="volSlider" type="range" min="-60" max="12" step="0.5" value="0" class="fader-slider w-28">
+          <div class="reaper-inset px-1 bg-white h-5 flex items-center justify-center w-14 font-mono text-[11px]">
+            <span id="volDbText">0.00 dB</span>
+          </div>
+        </div>
+
+        <div id="badgeType" class="px-2 py-0.5 bg-purple-950 text-purple-300 border border-purple-800 font-mono font-bold text-[10px] rounded-sm">
+          MIDI
+        </div>
+      </div>
+
+      <!-- CANVAS & METADATA ROW -->
+      <div class="flex items-stretch gap-2 my-1 h-16">
+        <div class="flex-1 reaper-dark-inset relative overflow-hidden">
+          <canvas id="previewCanvas" class="w-full h-full block cursor-pointer"></canvas>
+        </div>
+
+        <div class="w-56 reaper-dark-inset p-1.5 font-mono text-[10px] text-slate-300 leading-tight overflow-y-auto">
+          <div id="metadataContent">
+            76 MIDI events<br>
+            Length: 16 quarter notes<br>
+            Length: 0:08.000 (est)<br>
+            Ticks per quarter note: 480
+          </div>
+        </div>
+      </div>
+
+      <!-- BOTTOM STATUS BAR -->
+      <div class="h-5 bg-[#c0c0c0] border-t border-[#ffffff] flex items-center justify-between text-[11px] font-mono px-1">
+        <div class="flex items-center gap-3">
+          <div id="timeRange" class="reaper-inset px-1.5 bg-white text-slate-900 font-bold">0.0000 / 16.0000</div>
+          <div class="reaper-inset px-1.5 bg-white text-slate-900">0.0000</div>
+          <div class="reaper-inset px-1.5 bg-white text-slate-900">16.0000</div>
+        </div>
+
+        <div id="statusFileName" class="text-slate-800 font-bold truncate max-w-xs">File_Selected.mid</div>
+        <div id="statusBpm" class="text-slate-700">130 bpm x0.923</div>
+      </div>
+
+    </div>
+
+  </div>
+
+  <!-- SCRIPT LOGIC -->
+  <script>
+    const sampleDb = {
+      midi: [
+        { name: "MIDI_Loop_01.mid", events: 95, lengthQn: 16, time: "0:08.000", tpqn: 480, bpm: 130 },
+        { name: "MIDI_Loop_02_Bass.mid", events: 48, lengthQn: 16, time: "0:08.000", tpqn: 480, bpm: 130 },
+        { name: "MIDI_Loop_03_Lead.mid", events: 110, lengthQn: 16, time: "0:08.000", tpqn: 480, bpm: 130 },
+        { name: "MIDI_Loop_04.mid", events: 76, lengthQn: 16, time: "0:08.000", tpqn: 480, bpm: 130 },
+        { name: "MIDI_Loop_05_Bass.mid", events: 52, lengthQn: 16, time: "0:08.000", tpqn: 480, bpm: 130 },
+        { name: "MIDI_Loop_06.mid", events: 88, lengthQn: 16, time: "0:08.000", tpqn: 480, bpm: 130 }
+      ]
+    };
+
+    let selectedFile = sampleDb.midi[3];
+    const fileListTbody = document.getElementById('fileListTbody');
+    const previewCanvas = document.getElementById('previewCanvas');
+    const canvasCtx = previewCanvas.getContext('2d');
+
+    function renderFiles() {
+      fileListTbody.innerHTML = '';
+      sampleDb.midi.forEach((f) => {
+        const tr = document.createElement('tr');
+        tr.className = `cursor-pointer hover:bg-blue-100 ${f.name === selectedFile.name ? 'file-row-selected' : ''}`;
+        tr.innerHTML = `<td class="py-1 px-2 flex items-center gap-2"><i class="fa-solid fa-music text-purple-600 file-icon"></i><span>${f.name}</span></td>`;
+        tr.onclick = () => {
+          selectedFile = f;
+          renderFiles();
+          updatePreview();
+        };
+        fileListTbody.appendChild(tr);
+      });
+    }
+
+    function updatePreview() {
+      document.getElementById('statusFileName').innerText = selectedFile.name;
+      document.getElementById('metadataContent').innerHTML = `${selectedFile.events} MIDI events<br>Length: ${selectedFile.lengthQn} quarter notes<br>Length: ${selectedFile.time} (est)<br>Ticks per quarter note: ${selectedFile.tpqn}`;
+      renderCanvas();
+    }
+
+    function renderCanvas() {
+      previewCanvas.width = previewCanvas.clientWidth;
+      previewCanvas.height = previewCanvas.clientHeight;
+      const w = previewCanvas.width, h = previewCanvas.height;
+      canvasCtx.clearRect(0, 0, w, h);
+
+      // Grid
+      canvasCtx.strokeStyle = '#222';
+      for (let y = 0; y < h - 14; y += 8) {
+        canvasCtx.beginPath(); canvasCtx.moveTo(0, y); canvasCtx.lineTo(w, y); canvasCtx.stroke();
+      }
+      canvasCtx.strokeStyle = '#333';
+      for (let b = 0; b <= 16; b += 4) {
+        const x = (b / 16) * w;
+        canvasCtx.beginPath(); canvasCtx.moveTo(x, 0); canvasCtx.lineTo(x, h - 14); canvasCtx.stroke();
+      }
+
+      // Notes
+      canvasCtx.fillStyle = '#9ca3af';
+      for (let i = 0; i < selectedFile.events; i++) {
+        const noteX = ((i * 17 + 76) % 95) / 100 * w;
+        const noteY = ((i * 13 + 76) % (h - 24)) + 4;
+        canvasCtx.fillRect(noteX, noteY, Math.max(8, (i % 5 + 1) * 12), 3);
+      }
+
+      // Bar Ruler
+      canvasCtx.fillStyle = '#111';
+      canvasCtx.fillRect(0, h - 14, w, 14);
+      canvasCtx.fillStyle = '#888';
+      canvasCtx.font = '9px JetBrains Mono';
+      for (let b = 0; b <= 12; b += 4) {
+        canvasCtx.fillText(b.toString(), (b / 16) * w + 2, h - 3);
+      }
+    }
+
+    window.onload = () => { renderFiles(); updatePreview(); };
+  </script>
+</body>
+</html>
+
+```

mixer_panel_backup_20260729_0941.patch

@@ -0,0 +1,564 @@
+From 46d3778a5d5305ba625318433b7f98c1e4dac932 Mon Sep 17 00:00:00 2001
+From: 3dtours <yeunhiepanh.photo@gmail.com>
+Date: Wed, 29 Jul 2026 09:11:54 +0700
+Subject: [PATCH] =?UTF-8?q?FIX:=20chi=E1=BB=81u=20cao=20c=E1=BB=A7a=20trac?=
+ =?UTF-8?q?k=20thu=20nh=E1=BB=8F=20theo=20chi=E1=BB=81u=20cao=20c=E1=BB=A7?=
+ =?UTF-8?q?a=20Mixer=20Panel?=
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+
+---
+ .kilo/plans/mixer-equalizer-plan.md           | 293 ++++++++++++++++++
+ .../js/services/audioMixerGraphManager.js     |  20 +-
+ app/storage/sonicforge.db                     | Bin 77824 -> 77824 bytes
+ app/templates/index.html                      |   2 +-
+ 4 files changed, 310 insertions(+), 5 deletions(-)
+ create mode 100644 .kilo/plans/mixer-equalizer-plan.md
+
+diff --git a/.kilo/plans/mixer-equalizer-plan.md b/.kilo/plans/mixer-equalizer-plan.md
+new file mode 100644
+index 0000000..2fbf79e
+--- /dev/null
++++ b/.kilo/plans/mixer-equalizer-plan.md
+@@ -0,0 +1,293 @@
++# Mixer Console & Equalizer Implementation Plan
++
++## Goal
++Implement a docked Mixer Console panel (similar to REAPER's MCP) at the bottom of the DAW, featuring per-track channel strips with volume fader, pan knob, Mute/Solo, VU meter, and FX controls. Support MAIN SESSION and SECTION-TAB contexts with hierarchical audio routing.
++
++---
++
++## Task 1: Create `AudioMixerGraphManager`
++
++**File:** `app/static/js/services/audioMixerGraphManager.js` (new)
++
++Class managing all Web Audio nodes with a proper Master Bus signal chain:
++
++```
++source → trackGain → faderGain → panNode → analyserNode → masterGain → masterPan → masterAnalyser → destination
++```
++
++### Responsibilities
++
++- **Singleton pattern** — created once with `audioCtx`, stored on `window.AudioMixerGraphManager`.
++- **Master Bus** — `masterGain → masterPan → masterAnalyser → audioCtx.destination`.
++- **Track Node Map** — `Map<trackId, { inputGain, faderGain, panNode, analyserNode, track }>`.
++- **Section Bus Map** — `Map<sectionId, { subMixGain, subMixPan, hostTrackId }>`.
++- `createMainTrackNodes(track)` — creates node chain, connects analyser → masterGain. Stores in `trackNodesMap`. Calls `updateTrackVolumePan()`.
++- `createSectionSubMixBus(sectionId, hostTrackId)` — creates subMixGain→subMixPan, pipes to host track's `inputGain`. Falls back to masterGain if host track not found.
++- `createSectionTrackNodes(sectionId, secTrack)` — creates nodes for internal section tracks, connects analyser → section's `subMixGain`.
++- `updateTrackVolumePan(trackId, volumeDb, panValue, isMuted)` — updates gain/pan in real-time. `gain = isMuted ? 0 : Math.pow(10, volumeDb / 20.0)`.
++- `getAnalyserData(trackId)` — returns `analyserNode` frequency/time-domain data for VU meter rendering.
++- `removeTrackNodes(trackId)` — disconnects and removes from map.
++
++### Signal Equations
++- `linearGain = isMuted ? 0 : Math.pow(10, volumeDb / 20.0)` — dB to linear scale.
++- `panValue = track.pan / 100` — existing -100..+100 range maps to -1.0..+1.0 `StereoPanner.pan`.
++- Use `setTargetAtTime(linearGain, ctx.currentTime, 0.01)` for smooth transitions.
++
++---
++
++## Task 2: Refactor `app.jsx` Audio Node Creation
++
++**File:** `app/static/js/app.jsx` — modify existing audio routing functions.
++
++### 2a. Replace `getOrCreateTrackNode()` with `AudioMixerGraphManager`
++
++Currently lines 10314-10343 create a local `{ gainNode, pannerNode }` per track and connect `pannerNode → context.destination`. Replace this with:
++
++```js
++function getOrCreateTrackNode(track, context) {
++  if (!window.AudioMixerGraphManager) return null;
++  const mgr = window.AudioMixerGraphManager;
++  const bundle = mgr.trackNodesMap.get(track.id);
++  if (bundle) return bundle.faderGain;
++  // Create nodes via AudioMixerGraphManager
++  mgr.createMainTrackNodes(track);
++  return mgr.trackNodesMap.get(track.id).faderGain;
++}
++```
++
++### 2b. Section Sub-Track Audio Routing
++
++Replace `getOrCreateSubTrackNode()` (lines 10344-10359) to:
++1. Create section sub-mix bus via `AudioMixerGraphManager.createSectionSubMixBus()` (first time only, lazy init).
++2. Create section internal track nodes via `AudioMixerGraphManager.createSectionTrackNodes()`.
++3. Return `faderGain` node for audio connection.
++
++### 2c. SoundFont MIDI Audio Routing Fix
++
++**Critical:** FluidSynth renders directly to `audioCtx.destination` via ScriptProcessorNode. SoundFont player (`soundfontPlayer.js` lines 27-49) has its own `_gainNode` connected to destination. This bypasses the track's gain/panner nodes.
++
++**Fix in `soundfontPlayer.js`:**
++- Modify the first `_gainNode` creation so that instead of `_gainNode.connect(ctx.destination)`, it connects to a pass-through that can be dynamically routed to any destination node.
++- OR: In `startTrackPlayback()` (app.jsx ~line 10382), after calling `window.SonicSF.playNote(...)`, re-route the SF output by calling a new method `window.SonicSF.setOutputNode(destinationNode)` that disconnects the internal `_gainNode` from `destination` and reconnects it to the track's `faderGain`.
++
++**Simpler approach:** Add `setOutputNode(destinationNode)` to `soundfontPlayer.js`:
++```js
++function setOutputNode(newDest) {
++  _gainNode.disconnect();
++  _gainNode.connect(newDest || ctx.destination);
++}
++```
++
++Call this from `getOrCreateTrackNode()` after creating/retrieving the track's `faderGain`, passing `trackFaderGain` as the destination.
++
++---
++
++## Task 3: Mixer Console State & Toggle
++
++**File:** `app/static/js/app.jsx`
++
++### 3a. Add Mixer Visibility State
++
++```js
++const [showMixer, setShowMixer] = useState(false);
++```
++
++### 3b. Mixer Toggle Button
++
++Add a toolbar button (e.g., in the TCP header near the "Add Track" button, or in a bottom toolbar). Icon: "mixer" (sliders icon). Toggles `showMixer`.
++
++### 3c. Determine Active Context
++
++When `activeTab === 'main'`, mixer shows MAIN SESSION tracks. When a SECTION-TAB is active, mixer shows the section's internal tracks (from `sessionTabs.find(s => s.id === activeTab).tracks`).
++
++### 3d. Pass to MixerConsole
++
++```
++mixerContext = { isSectionTab, currentTracks, currentTitle, activeTabContext }
++```
++
++---
++
++## Task 4: Create MixerConsole React Component
++
++**File:** `app/static/js/components/MixerConsole.jsx` (new)
++
++Docked at the bottom of the timeline (inside the `bottom` dock panel or a fixed container at bottom of the `flex-1 flex flex-col overflow-hidden` area, below the timeline canvas).
++
++### 4a. Component Structure
++
++```
++MixerConsole (flex-col h-48 border-t border-zinc-700 bg-slate-900)
++├── MixerHeader (flex, shows "MAIN SESSION" or "SECTION TAB" label + close button)
++└── MixerStripsWrapper (flex-1 flex overflow-x-auto p-2 gap-1.5)
++    ├── MasterChannelStrip (w-28, fixed, left-aligned)
++    ├── Divider (w-[1px] bg-zinc-700)
++    └── Track strips (horizontal scroll, each TrackChannelStrip w-24)
++```
++
++### 4b. MasterChannelStrip
++
++Props: `isSectionBus, mixerGraphMgr`
++
++- Shows "MASTER" or "SEC BUS" header.
++- VU Meter canvas element (reads `masterAnalyser` frequency data, draws RMS/Peak bar).
++- Peak/rms numeric readout.
++- Mono toggle button.
++- "MAIN OUT" / "SUB-MIX" footer.
++
++### 4c. TrackChannelStrip
++
++Props: `track, index, mixerGraphMgr`
++
++Local state: `volumeDb, pan, isMuted, isSoloed` — initialized from `track` props.
++
++Renders:
++1. **Pan knob** — `<input type="range" min="-1" max="1" step="0.05">` vertical/horizontal slider + numeric label (C / Lxx / Rxx).
++2. **dB Readout** — `volumeDb <= -60 ? "-inf" : "[+/-]N.NdB"`.
++3. **Mute / Solo buttons** — `[M]` orange when muted, `[S]` yellow when soloed. Mute dispatches `updateTrackVolumePan(trackId, vol, pan, newMute)`. Solo dispatches `toggleTrackSoloEvaluate(trackId)`.
++4. **Fader + VU Meter** — vertical fader `<input type="range" min="-60" max="+12" step="0.5">` with CSS `writing-mode: vertical-lr`. VU meter bar (vertical `div` with gradient, height calculated from analyser RMS data). RequestAnimationFrame loop reads `analyserNode.getByteTimeDomainData()` and updates VU height.
++5. **FX / Power buttons** — `[FX]` stub that shows toast "FX panel coming soon". `[⑈]` bypass toggle (stub).
++6. **Footer** — `{index}. {track.name}` + `{track.type}`.
++
++### 4e. VU Meter Animation
++
++Use `requestAnimationFrame` loop inside `TrackChannelStrip`:
++```js
++useEffect(() => {
++  const analyser = mixerGraphMgr?.trackNodesMap.get(track.id)?.analyserNode;
++  if (!analyser) return;
++  analyser.fftSize = 128;
++  const bufferLength = analyser.frequencyBinCount;
++  const dataArray = new Uint8Array(bufferLength);
++  let rafId;
++  const draw = () => {
++    analyser.getByteTimeDomainData(dataArray);
++    const rms = Math.sqrt(dataArray.reduce((sum, v) => sum + ((v - 128) / 128) ** 2, 0) / bufferLength);
++    setMeterLevel(Math.min(1, rms * 2));
++    rafId = requestAnimationFrame(draw);
++  };
++  rafId = requestAnimationFrame(draw);
++  return () => cancelAnimationFrame(rafId);
++}, [track.id, mixerGraphMgr]);
++```
++
++---
++
++## Task 5: Add Mixer Toggle Button (TCP Header)
++
++**File:** `app/static/js/app.jsx` — TCP header area (line 16648-16656).
++
++Add a mixer toggle button next to the "Add Track" button:
++
++```jsx
++/*#__PURE__*/React.createElement("button", {
++  onClick: () => setShowMixer(!showMixer),
++  className: "px-2 py-1 bg-indigo-700 hover:bg-indigo-600 text-white rounded text-xs font-semibold flex items-center gap-1 shadow transition"
++}, /*#__PURE__*/React.createElement("span", {
++  className: "inline-flex items-center shrink-0"
++}, /*#__PURE__*/React.createElement("i", {
++  "data-lucide": "sliders-horizontal",
++  className: "w-3.5 h-3.5"
++})), " Mixer")
++```
++
++## Task 6: Add F7 Keyboard Shortcut for Mixer Toggle
++
++**File:** `app/static/js/app.jsx` — modify the global keyboard handler (lines 8037-8335).
++
++The keydown handler at line 8334 (`window.addEventListener('keydown', handler, { capture: true })`) already handles hotkeys like Space (play/pause) and function keys for sub-tab operations.
++
++Add an `F7` check inside the handler, **before** the sub-tab-only block at line 8054 (so it works in both MAIN SESSION and sub-tabs):
++
++```js
++// F7: Toggle Mixer Console
++if (e.key === 'F7') {
++  e.preventDefault();
++  setShowMixerRef.current(prev => !prev);
++  return;
++}
++```
++
++Use a ref (`showMixerRef`) to access the current `showMixer` state without needing it as a dependency of the effect. Create the ref and keep it synced in the component body:
++
++```js
++const showMixerRef = useRef(showMixer);
++showMixerRef.current = showMixer;
++```
++
++Keep `setShowMixerRef` as a ref to `setShowMixer` to call it from the event listener without stale closures.
++
++This avoids adding `showMixer` as a dependency to the keyboard effect, which would cause unnecessary listener re-registrations.
++
++---
++
++## Task 7: Integrate MixerConsole into App Layout
++
++**File:** `app/static/js/app.jsx`
++
++### 5a. Placement
++
++After the timeline track list (the `div` containing `activeTracks.map(...)` and the add-track row), and before the transport bar, insert:
++
++```jsx
++showMixer && React.createElement(MixerConsole, {
++  key: 'mixer-console',
++  mixerContext: { isSectionTab, currentTracks, currentTitle, activeTabContext },
++  mixerGraphMgr: window.AudioMixerGraphManager,
++  trackActions: { updateTrackVolumeDb, updateTrackPan, toggleTrackMute, toggleTrackSoloEvaluate }
++})
++```
++
++### 5b. Panel System Integration
++
++Alternatively, register "mixer" as a panel that can be docked to the `bottom` dock panel. The panel content renders `MixerConsole`. This reuses the existing `dockPanels` / `renderDock` system — add a menu item or button that calls `addToDock('bottom', 'mixer')`.
++
++Simpler approach: fixed position below the timeline with a toggle button.
++
++---
++
++## Task 8: Section-Tab Context Switching
++
++**File:** `app/static/js/app.jsx`
++
++When `activeTab` changes to a SECTION-TAB (`sessionTabs.some(s => s.id === activeTab)`):
++- MixerConsole's `currentTracks` switches to the section's internal tracks.
++- The Master strip label changes from "MASTER" to "SEC BUS".
++- Header shows "MIXER: SECTION TAB ({sectionName})".
++- Audio routing uses `createSectionSubMixBus` + `createSectionTrackNodes`.
++
++When switching back to `activeTab === 'main'`:
++- MixerConsole reverts to MAIN SESSION tracks and Master strip.
++
++This logic lives inside a `useEffect` that watches `activeTab` and re-renders the MixerConsole with the correct context.
++
++---
++
++## Task 9: Mixer Resize & Toggle Persistence
++
++- Add a top drag handle on the MixerConsole (`h-1 cursor-ns-resize hover:bg-cyan-500/50`) to adjust height (range: `h-32` to `h-80`). Store height in a ref.
++- Store `showMixer` and mixer height in `localStorage` for persistence.
++- Close button (`[X]`) on the Mixer header sets `showMixer = false`.
++
++---
++
++## Validation Plan (Additions for F7 + Toggle Button)
++
++1. [ ] **Button toggle** — Click "Mixer" button in TCP header → MixerConsole appears. Click again → hides.
++2. [ ] **F7 hotkey** — Press F7 → MixerConsole toggles. Works in both MAIN SESSION and SECTION-TAB. Does NOT interfere with input/textarea focus.
++3. [ ] **No stale closure** — Repeated F7 presses reliably toggle state (setShowMixerRef.current used, not a stale function).
++
++## Extended Validation Plan
++
++1. **Toggle mixer** — Click the Mixer button → MixerConsole appears at bottom. Click again → hides.
++2. **MAIN SESSION mode** — Shows all tracks in the session. Master strip on left.
++3. **Volume fader** — Drag fader → track volume changes audibly in real-time. Numeric dB readout updates.
++4. **Pan knob** — Drag pan → stereo position changes. Label shows C / Lxx / Rxx.
++5. **Mute** — Click [M] → track mutes, button turns orange. Click again → unmutes.
++6. **Solo** — Click [S] on track 1 → track 1 plays, all other tracks silence. Click again → all tracks resume.
++7. **VU Meter** — During playback, meter bars animate with signal level (green/yellow/red gradient).
++8. **SECTION-TAB** — Open a section → MixerConsole switches to section tracks, Master strip shows "SEC BUS".
++9. **Section sub-mix volume** — Adjust fader on the SECTION host track → entire section volume changes.
++10. **MIDI audio routing** — SoundFont MIDI notes play through the track's fader/panner, not bypassing.
++11. **Resize** — Drag the resize handle on top of MixerConsole → height changes.
++12. **Persistence** — Reload page → mixer state restored from localStorage.
+diff --git a/app/static/js/services/audioMixerGraphManager.js b/app/static/js/services/audioMixerGraphManager.js
+index 93c530b..60c39c2 100644
+--- a/app/static/js/services/audioMixerGraphManager.js
++++ b/app/static/js/services/audioMixerGraphManager.js
+@@ -4,10 +4,22 @@
+   function AudioMixerGraphManager(audioCtx) {
+     this.audioCtx = audioCtx;
+     this.trackNodesMap = new Map();
+-    this.sectionBusMap = new Map();
+-
+-    // Master bus chain: masterGain -> masterPan -> masterAnalyser -> destination
+-    this.masterGain = audioCtx.createGain();
++      this.sectionBusMap = new Map();
++      this.trackFxBypassGains = new Map();
++
++      // Master bus chain: masterGain -> masterPan -> masterBypassGain -> masterAnalyser -> destination
++      this.masterGain = audioCtx.createGain();
++      this.masterGain.gain.setValueAtTime(1, audioCtx.currentTime);
++      this.masterPan = audioCtx.createStereoPanner();
++      this.masterPan.pan.setValueAtTime(0, audioCtx.currentTime);
++      this.masterBypassGain = audioCtx.createGain();
++      this.masterBypassGain.gain.setValueAtTime(1, audioCtx.currentTime);
++      this.masterAnalyser = audioCtx.createAnalyser();
++      this.masterAnalyser.fftSize = 128;
++      this.masterGain.connect(this.masterPan);
++      this.masterPan.connect(this.masterBypassGain);
++      this.masterBypassGain.connect(this.masterAnalyser);
++      this.masterAnalyser.connect(audioCtx.destination);
+     this.masterGain.gain.setValueAtTime(1, audioCtx.currentTime);
+     this.masterPan = audioCtx.createStereoPanner();
+     this.masterPan.pan.setValueAtTime(0, audioCtx.currentTime);
+diff --git a/app/storage/sonicforge.db b/app/storage/sonicforge.db
+index b1d2ec94d1a0c8be003360e1202979abb9d62c6c..0ffa5a826df5e7beabb1bee853e683414f554125 100644
+GIT binary patch
+delta 1068
+zcmV+{1k?L~-~@o+1dtmIp8x;=6951J5dZ)H29YQ?0iUs85FY^vlW`wHKsjPDIWspl
+zH)J(pH#0ObH8f*2V_{=rW@b1zGG;b2HaIb6GB{#mH8eM3FfleWFl1(AWH2#dGdX5v
+zHDfX{FthU?5nu`f50U^6k`L|=z_Sq`gb$Ozj|n9-F*!6aI5;^iF*rG8Ei`0iG%YwW
+zV=^sdVlZQ2VKp=~VK8L_v%rr;FtY{V{0|Hb3zPr?2gCpjEeFK0fw%`*hfM<sUsXSi
+zH3<R-bY*RDUo<f}G%z?gIV~|bIb|(0WM(uiI5A@~Eo5RaV_{)6G&Er_Wi&B4G%z?g
+zIV~|bIb|(0WM(uiI5A@~Eo5RaV_{)6G&Er_Ws_^sC?j-bZE#<3a&Ky7V{{@cB5h@K
+zVPs)+VIn$vB6MkVY-J)kB9m*;8I#h{<`-0QVPk6`Ffk%5B6N9hWg<EvK~+RaPm{UF
+zLN#u6Y-}tdX>N0La&>KGZggL8a&KpHVQnHhZgp&IEFx)cb98cbZDnqBUv6P-Wg<Fm
+zb!=>tK*$v?Zgp&IEFyDnb#7#4Z*Fv7X=EZgZgp&IEFyDnb#7#4Z*Fv7VqtD;B06q$
+zY;2Pd)D=2zb!==bB58DGZF3?zTU~uDdm?FMB03^6A}k_qVQpn1IwDkZVPk6`Fft-6
+zB6N9hWg<EvK~+RaPm{UFLN#u6Y-}tdX>N0La&>KGZggL8a&KpHVQnHhZgp&IEFx)c
+zb98cbZDnqBUv6P-Wg<Fmb!=>tK*$v?Zgp&IEFyDnb#7#4Z*Fv7X=EZgZgp&IEFyDn
+zb#7#4Z*Fv7VqtD;B06q$Y;2Pd)D;eHb!==bB58DGZF3?zTa(bwCJqBsLE4&AiE|l4
+z0001)k%5&7hfo3uUsXSiJF^?nodFkAa$#d@ATTi^EFyGyaAhJoB0*I|Nl%lx$3iu3
+zb!==bB57`ObaHiVWo~p|aB^>Fa$#*EI&O7rY%C&aZgX^Ub!}yCbYE^^ZDk@lZgp&I
+zlR(H7E^c*fY%C&kZ*^{DW^ZnEUuk3_I&O7rY%C&kZ*^{DW^ZnEUt(cyYa%*sb!=>t
+z5Y!bqZgp&IEFx)iWo>gJI$K?REPEnpWFk5uG9oM@ZeeX@B03^ea$#d@ATTl_EFyGy
+zaAhJoB0*I|Nl%lx$3iu3b!==bB57`ObaHiVWo~p|aB^>Fa$#*EI&O7rY%C&aZgX^U
+zb!}yCbYE^^ZDk@lZgp&IlR(H7E^c*fY%C&kZ*^{DW^ZnEUuk3_I&O7rY%C&kZ*^{D
+zW^ZnEUt(cyYa%*sb!=>t5Y!b8Zgp&IEFx)iWo>gJI$M*_&n5~3S3%mESWSxm%(DUD
+m1|Svy1poj55C8xG6951J5&!@I4*&oF4YL8@1|YK_aNZB((q(7>
+
+delta 7203
+zcmV+;9Ngo8-~@o+1dtmIV*mgE6951J5dZ)H1(7H>0b{XX5FY^ulW`wHKw~*EVl+8n
+zHaB53W@a~GF=jbAIW;&mVK!o9G-NP2GB;v5VPP{lV=yo@IbvfpI5uW7F=aVrGd3}1
+zVl`uBF|+d@5nu=c55NEq?hnAT5iqn5v%rr;Fn?}eVr5};b0Ru0E;2PNB6ekLZ)0h6
+zc_KP6E;TG7aA9sDIxu}Kdm?FMB03^&Z**l}a%Ew1a$hkwI5jdfH#IOYF*z|`F*PDA
+zB5-MRV`w5eHa9FHb97;HbYEg+VRRxoIW9LfEFxrea$$67Z*E^=Wnpx4B04ZGGBqqB
+zc7J7TZ)0h6c_KP6E;KA6aA9sDIxu}Kdm?FMB03^&Z**l}a%Ew1a$hkwI5jdfH#IOY
+zF*z|`F*YJBB5-MRV`w5eH8(6Gb97;HbYEg+VRRxoF*YnBWOZ_3bZKvHUt(opbaNs)
+zFfKAREFyMgY;R*}ba^5=FfKMMB5+}DB7ZtCeJpz-X=EZgB5rSVWnXe-VRCX`F*i6h
+zGBh_eFfcJWF<&t^A}k_sX>?;~B04rOEFyDsVRCd|Vr5};B04cPE;2PNB4l-PVRUJ4
+zZeL<$VRUmMIxsFWH7p`_Wo&O_X>@raIxsFZEFy4WZX!A`eJpz-X=EZgB5rSVWq)6C
+zWnpr1Uokg0H8M0eH83zSIWb=`I3g?}aA|a7Xd*f`G%O->bYXIIUt(opbRs%2HZC<R
+zB4l-PVRUJ4ZeL<$VRUmMIxsFWH7p`_Wo&O_X>@raIxsFZEFy4WZX!A`eJpz-X=EZg
+zB5rSVWnXe-VRCX`F*i6hGBh_eFn=&HIWb=`IU+0~aA|a7Xd*f`IV>V`bYXIIUt(op
+zbRs%2HZC_cEFxrea$$67Z*E^=Wnpx4B04ZGGBqqBc4cgDV`+4GB04ZGG%O-;VQwNi
+zFnuh0B57nIIwEdwbY)+1Wnpr1Uokg0H8M0eH83zSIWb={Fd{4>aA|a7Xn!I)H8(6G
+zb97;HbYEg+VRRxoF*htCWOZ_3bZKvHUt(opbaNs)FfKAREFyMgY;R*}ba^5=FfKMM
+zB5+}DB04aAEPEnpWFk5uZf|sDUvgz(a&liWH#jviG&eOcFflnXUotTwEFy4ebYo~D
+zIyNvYB6D<Ma&%u}Wnpw8I)5=YE;2PNB4l-PVRUJ4ZeL<$VRUmMIxsFWH7p`_Wo&O_
+zX>@raIxsFZEFy4WZX!A`eJpz-X=EZgB5rSVWnXe-VRCX`F*i6hGBh_eFfcJWF<&w=
+zA}k_sX>?;~B04rSEFyDsVRCd|Vr5};B04cQE;TG7WOZ_3bZKvHUw>j{VRUmMIxsFW
+zH7p`_Wo&O_X>@raIxsFZEFy4WZX!A`eJpz-X=EZgB5rSVWnXe-VRCX`F*i6hGBh_e
+zFfcJWF<&w>A}k_sX>?;~B04rXEFyDsVRCd|Vr5};B04cQE;ltSB4l-PVRUJ4ZeL<$
+zVRUmMIxsFWH7p`_Wq)jMV`+4GB04ZGG%O-;VQwNiFnuh0B57nIIwEdwbY)+1Wnpr1
+zUokg0H8M0eH83zSIWb={G$Je_aA|a7Xd*f_IV>V`bYXIIUt(opbRs%3G%O-yb#h^J
+zX>V>{Vr5};b0Ru0E;2PNB6ekLZ)0h6c_KP6E;cM8aA9sDI)5;IEPEnpWFk5uZf|sD
+zUvgz(a&liWH#jviG&eOcFflnXUotf!EFy4ebYo~DIyN#aB6D<Ma&%u}Wnpw8Ix;ja
+zGBqqBWOZ_3bZKvHUt(opbaNs)FfKAREFyMgY;R*}ba^5=FfKJLB5+}DB04aAEPEnp
+zWFk5uZf|sDUw?9CVRCX`F*i6hGBh_eFfcJWF<&w^A}k_sX>?;~B04rUEFyDsVRCd|
+zVr5};B04fOE;TG7WOZ_3bZKvHUt(opbaNs)FfKAREFyMgY;R*}ba^5=FfKJLB5+}D
+zB04aAEPEnpWFk5uZf|sDUvgz(a&liWH#jviG&eOcFn=*QF<&w_A}k_sX>?;~B04uQ
+zEFyDsVRCd|Vr5};B04fOE;ltSB4l-PVRUJ4ZeL<$VRUmMIxsFWH7p`_Wo&O_X>@ra
+zIxsFYEFy4WZX!A`eJpz-X=EZgB5rSVWnXe-VRCX`F*i6hGBh_eFfcJWF<&w`A}k_s
+zX>?;~B7ZtHIV>V`bYXIIUt(opbRs%3H7p`zb#h^JX>V>{Vr5};b0Ru0E;2PNB6ekL
+zZ)0h6c_KP6E;cM8aA9sDIxu}Kdm?FMB03^&Z**l}a%Ew1a$hkwI5jdfH#IOYF*z|`
+zGC3kFB5-MRV`w5eHZm+Cb97;HbYEg+VRRxoGJiELGBqqBWOZ_3bZKvHUt(opbaNs)
+zFfKAREFyMgY;R*}ba^5=FfKJLB5+}DB04aAEPEnpWFk5uZf|sDUvgz(a&liWH#jvi
+zG&eOcFflnXUo$WwEFy4ebYo~DIyN>eB6D<Ma&%u}Wnpw8Ix;mbH7p`zb#h^JX>V>{
+zVt-{}baNs)FfKAREFyMgY;R*}ba^5=FfKJLB5+}DB04aAEPEnpWFk5uZf|sDUvgz(
+za&liWH#jviG&eOcFflnXUo$ZxEFy4ebYo~DIyW&aB6D<Ma&%u}Wnpw8Ix;mbH#ICG
+zWOZ_3bZKvHUt(opbaNs)FfKAREFyMgY(#HkX>@raIxsFYEFy4WZX!A`eO-NhU41Nj
+zB57nIIwCS6EFx}UZDk@lB0_Rub8{d~Z**y9A}k_wd2nSSIwDO;L`jo=*+LB>b7o&@
+zY;1LNX>V>KlQ7;EA~85DB57`ObaHiVWo~p|ZeeX@B03^dd2V!QAVP9sb8{k-Vcr!!
+zB6DwbZe(U}Zge6nB6DwbZe(U}ZggL1WFk5uXJu|>a$#(Bb7gX0XLBMfB6DwbZe(U}
+zZggK_VQy<8Ixv$#+Z9qVI4mM_d2V!QUuAA*X>MgAI(s5?d2nSSIwEs#b#7#4Z*FuV
+zEFy4hb!TaAUuk3_IwEssUukS?b#rNNZXzrqb8mHSWM*$}bYEg&ZfhbsFq1*s6@M`}
+zEFyDnb#7#4Z*Fv7X=EZgB57=Fb#rNNZX$gwB58DGZF3?zTYDmDWFk5uX>?_6Utwuq
+zF*i6hGBh_dHa0aiG+#1gZf<QNEFx}UZDk@lB1Ld%V<1m*V`yb_baG*AAW3d?WpZqF
+zWMv>iVRCaIGBqtTG9WD=LULhqbAKRBZ**y9A}k_wd2nSSIwDO;L`h#sR7Fi9EFyDs
+zVRCd|VqtP3Ixs9EWOZ_3bZKvHUt(c$b0Ru8EFxoUX>eb2bYXIIUvFk+b7gd2VqtP~
+zB04ZEB6Dwba${v*WMOn+B075_bZ>NFY+qt^W@cq_Ut(c$b0Ru8EFx}ibbn=YB05`p
+zB57nIIwEdwbY)**X<sonI5jdfH#9ajH8nI}Fd{4>aA|a7Xd*f`G%O->bYXIIUt(op
+zbRs%3EFxrea$$67Z*E^=Wnpx4B04fGB6ekLZ)0h6c_KP6E;B45aA9sDIxu}Kdm?FM
+zB03^&Z**l}VQF76H#jviG=DcVHa0aiG+!|yEFy4ebYo~DIyN^fB6D<Ma&%u}Wnpw8
+zIyNjKWOZ_3bZKvHUt(opbaNs)GAtr?Wo&O_X>@raIxsFXEFy4WZX!A`eJpz-X=EZg
+zB5rSVWnW=wUokg0H8M0eG&VLhH8fu`A}k_sX>?;~B04rSEFyDsVSjRTUt(opbRs%2
+zI4mM$b#h^JX>V>{Vr5};b0Ru2EFyMgY;R*}ba^5=FfKDJB5+}DB04aAEPEnpWFk5u
+zZf|sDUtwuqF*i6hGBh_dHa0aiG+#3!EFy4ebYo~DIyN^fB6D<Ma&%u}Wnpw8Ix;dW
+zB4l-PVRUJ4ZeL<$VNG;%B04fGB6ekLZ)0h6c_KP6E;B45aA9sDIxu}*eSKYhEPEnp
+zWFk5uGa@V^ZeeX@B03^eVQFh`AV_I+b0RDvba`-PB03^XNkmDLe%V3|B6DV6b7^j7
+zZ*DU-B9k!Q7AY_+B57`ObaHiVWo~p|ZeeX@B03^Oa&>JWTT^slZZTaTEmK1{I8Y*!
+zVcr!$B6DwbZe(U}Zge6nB6DwbZe(U}ZggL1WFk5uXJu|>a$#(Bb7gX0XLBMfB6Dwb
+zZe(U}ZggK_VQy<8Ix#XhlR?`RQ!p$db9rubXkTS+XK8L_B075_ba`-PB03^-Z*^{D
+zW^ZnEA}k_sY;|X8ZeM9+B03^-W?yq@Zf0+8Gd3bDB6DwbZe(U}ZggK_VQy<8Ix#Xh
+zlR?`Re=sZ}b8mHSWM*$}bYE#?B03^-X>Mk3ZZkF_eJmnrbY*RGB05`pB57nIIwEOw
+zWo=(!X<sonI5jdfH#9ajH8nI}WpieFY9cHmZeeX@B03^PaA{*8PjX{uWpi|LVQe5t
+zZggdGY;|O1AVOhsb09J`Ei*D8Eg)23X=`sFe@JO`b0RDvba`-PB03^XNkmCsNmNBm
+zA}k_vbYXIIUt(c$B04ZEB4l-PVRUJ4ZeL<ya&sa&I4mM#Y-w;`b97;HbYE{~W^-k9
+zUt(c$b0Ru0EFyDnb#h~6Uu0o)VIn$vB6M$bVQgPwb!KK|a$jO$a&sa&I4mM=Z**mI
+ze<C_tdm?FMB03^&Z**l}VQF76H#jviG&eLhHZ?UgUoavpB5-MRV`w5eGd3(Db97;H
+zbYEg+VRRxoFf1Zub#h^JX>V>{Vr5};b0Ru1EFyMgY;R*}ba^5=FfKJLB5+}DB04aA
+zEPEnpWFk5uZf|sDUtwuqF*i6hGBh_de>OHXH8fu_A}k_sX>?;~B04iREFyDsVRCd|
+zVr5};B04xMB4l-PVRUJ4ZeL<$VRUmMIx#FFc4cgDV`+4GB04ZGH7p`<VQwNiFnuh0
+zB57nIIwEdwbY)**X<sonI5jdfH#9ajH8nI}G9oM@aA|a7Xd*f@HY_4@bYXIIe_vu{
+zVRRxoF*YnBWOZ_3bZKvHUt(opbaNs)F)Si>Wo&O_X>@raIxsFZEFy4WZX!A`eJpz-
+zX=EZgB5rSVWnW=wUokg0H8M0eG&VLhH8fu{A}k_sX>?;~B04iREFyDsVRCd|Vr5};
+zB04fOEFxrea$$67Z*E^=Wnpx49wIt1EFyMgY;R*}ba^5=FfKJLB5+}DB04aAU44C%
+z(BCE$9%@0_nl0}B-C_*@000325&!`bv4IEy3B6+i313w|`C+p*+?@d&Q*?4^ZfA2K
+zOl4<bbZ;UoB6N9hWg<EvO-V#alYZGk4I*=9Uvp`0W^ZmYHX@TS-WDA+Ff1ZzZgX^U
+zb!}yCbYE^^ZDk@lB35Z{Y-w&HlVRQ!J|c5(b#7#4Z*FuVEFyDnb#7#4Z*Fv7X=EZg
+zB4=f8WpZI`b#rBMUuSb7EFyDnb#7#4Z*Fv7VqtD;B04aWLE9BlG%ze8b9rubXkTS+
+zXK8L_B075_ba`-PB03^-Z*^{DW^ZnEA}k_sY;|X8ZeM9+B03^-W?yq@Zf0+8Gd3bD
+zB6DwbZe(U}ZggK_VQy<8Ixv$#+ZBH_Ff1Z-Z*^{DW^ZnEUuk3_IwEsvZf0+8Gd3c9
+zEFx)iWo>gJI$L`pX=EZgB58DGZC_z&Uokg0H8M0eG&VLhG%;UcHZ^HAA}k_qVQpn1
+zIwD1IX=5Nya${&^b98cHY#>Q)bY*gEb!25ALSb@qATl*AGcq78AX9X5X>NaKb0AD*
+zXJK@2A}k_wd2nSSIwDO;L`h#sR7Fi9EFyDsVRCd|VqtP3Ixs9EWOZ_3bZKvHUt(c$
+zb0Ru8EFxoUX>eb2bYXIIUvFk+b7gd2VqtP~B04ZEB6Dwba${v*WMOn+B075_bZ>NF
+zY+qt^W@cq_Ut(c$b0Ru8EFynyZ**mIB05`pB57nIIwEdwbY)**X<sonI5jdfH#9aj
+zH8e3_Fd{4>aA|a7Xd*f_GAtr<bYXIIUt(opbRs%1EFxrea$$67Z*E^=Wnpx4B04xM
+zB6ekLZ)0h6c_KP6E;KA6aA9sDIxu}Kdm?FMB03^&Z**l}VQF76H#mPaGBh_dHa0ah
+zF<&tvEFy4ebYo~DIyE&cB6D<Ma&%u}Wnpw8IyfvMWOZ_3bZKvHUt(opbaNs)I4mM|
+zWo&O_X>@raIxsFYEFy4WZX!A`eJpz-X=EZgB5rSVWnW=wUokg0H8M0eG&VLhG%;T?
+zA}k_sX>?;~B04oUEFyn%bYXIIUt(opbRs%2HY_4!b#h^JX>V>{Vr5};b0Ru8EFyMg
+zY;R*}ba^5=FfKGKB5+}DB04aAEPEnpWFk5uZf|sDUtwuqF*i6hGBh_dHa0ahF<&zx
+zEFy4ebYo~DIyE^gB6D<Ma&%u}Wnpw8Ix;jYB4l-PVRUJ4ZeM?5Wnpx4B04xMB6ekL
+zZ)0h6c_KP6E;KA6aA9sDIxu}*eSKYhEPEnpWFk5uG$Je_ZeeX@B03^lK}jG|Wnpr1
+zVQyz-T_8bnaAjv_X>TA_VRC6<bZKvHAa7<MMQ~|jAX9X5X>Mn8A}k_wd2nSSIwDO;
+zL`fnnB6e?Vb#0S|**Y5{b7o(2bY*F7cVT&7V{dL_WpZ?1aA{#~Zz7X0-WDA&EFx)c
+zb98cbZDnqBUv6P-Wg<EvP-$UqZy+%ulVRQ!Mj~@>b#7#4Z*FuVEFyDnb#7#4Z*Fv7
+zX=EZgB6D<QX>NC6d0%61ZewL~bYF03VQz0CEFyDnb#7#4Z*Fv7VqtD;B04aWLE9By
+zFf1Z-d2V!QUuAA*X>MgAI(s5?d2nSSIwEs#b#7#4Z*FuVEFy4hb!TaAUuk3_IwEss
+zUvqS2X>NC6d0%61ZewL~bYF03VQz0CEFyDnb#7#4Z*Fv7VqtD;B04aWLE9C7Ff1Z-
+zZ*^{DW^ZnEUuk3_IwEs)Wod4AVR>I;Z*F5{a&%vCX<=?}B7H0(X>?_6b0Ruhdm?FM
+zB03^zbY*Q{a%Ew1a$hkwI5jdfH#IOYF*z|`WNB+|WFjmgZeeX@B03^lK}lU8L2__q
+zXJ=_|AXZ^=X<>9}Z*CxOW*|j>aA{*8Q*?4^ZfA2KEg*Jbaw04uba`-PB03^XNkmCs
+zNmNBmA}k_vbYXIIUt(c$B04ZEB4l-PVRUJ4ZeL<ya&sa&H!e9iHa0ggFf=eVF*rFl
+zGBqqBV{B<~UvqR}a&%vBW@d9`bYEg&a&sa&Ff1Z-Z*_8GWnW}rbYUWYI(s5?Z**a7
+zUt)D;W@U0;VqtP~B04uNIXE^pH!(0YFf}naIX5yjEFx}ibY*iQI$L`pX=EZgB5rSV
+zWnXe-VRCX`F*i6hGBh_eFfcJWF<&quEFy4ebYo~DIyEvZB6D<Ma&%u}Wnpw8Ixs9E
+zWOZ_3bZKvHUt(opbaNtqIxsFWH7p`_Wo&O_X>@raIxsFaEFy4WZX!A`eJpz-X=EZg
+zB5rSVWnXe-VRCX`F*i6hGBh_eFfcJWF<&tvEFy4ebYo~DIyE&cB6D<Ma&%u}Wnpw8
+zIxsFWH7p`zb#h^JX>V>{Vr5};b0Ru0E;2PNB6ekLZ)0h6c_KQ0FfKJLB5+}DB04aA
+zEPEnpWFk5uZf|sDUvgz(a&liWH#jviG&eOcFflnXUos*rB5-MRV`w5eH90IIb97;H
+zbYEg+VRRxoFfKJLB4l-PVRUJ4ZeL<$VRUmMIxsFWH7p`_Wo&O_X>@raIxsFZEFy4W
+zZX!A`eJpz-X=EaQIwEdwbY)+1Wnpr1Uokg0H8M0eH83zSIWb=|A}k_sX>?;~B04rS
+zEFyDsVRCd|Vr5};B04ZGH#ICGWOZ_3bZKvHUt(opbaNs)FfKAREFyMgY;R*}ba^5=
+zFfKGKB5+}DB04aAEPEnpWFk5uZf|sDUvgz(a&liWH#jwaGBh_eFfcJWF<&$yEFy4e
+zbYo~DIyEvZB6D<Ma&%u}Wnpw8Ix#FFWOZ_3bZKvHUt(opbaNs)FfKAREFyMgY;R*}
+zba^5=FfKMMB5+}DB04aAEPEnpWFk5uZf|sDUvgz(a&liWH#jviG&eOcFflnXUo|2u
+zB5-MRV`w6OIyE&cB6D<Ma&%u}Wnpw8Ix#LXH7p`zb#h^JX>V>{Vr5};b0Ru0E;2PN
+zB6ekLZ)0h6c_KP6E;TG7aA9sDIxu}Kdm?FMB03^&Z**l}a%Ew1a$hkwI5jdfH#IOY
+zF*z|`HX<w{aA|a7Xd*f_IV>V`bYXIIUt(opbRs%`F)lSMB4l-PVRUJ4ZeL<$VRUmM
+zIxsFWH7p`_Wo&O_X>@raIxsFZEFy4WZX!A`eJpz-X=EZgB5rSVWnXe-VRCX`F*i6h
+zGBh_eFfcJWF<&<#EFy4ebYo~DIyN*cB6D<Ma&%u}Wnpw8Ix#LcH7p`zb#h^JX>V>{
+zVr5}}baNs)FfKAREFyMgY;R*}ba^5=FfKGKB5+}DB04aAEPEnpWFk5uZf|sDUvgz(
+za&liWH#jviG&eOcFflnXUpOKxB5-MRV`w5eH8m_Eb97;HbYEg+VRRxoI4mM$b#h^J
+zX>V>{Vr5};b0Ru0E;2PNB6ekLZ)0h6c_KQ0FfKMMB5+}DB04aAEPEnpWFk5uZf|sD
+zUvgz(a&liWH#jviG&eOcFflnXUpXQyB5-MRV`w5eH90IIb97;HbYEg+VRRxoI4&|Z
+zEFxrea$$67Z*E^=Wnpx4B04ZGGBqqBc4cgDV`+4GB04ZGH7p`<VQwNiFnuh0B57oQ
+zB03^&Z**l}a%Ew1a$hkwI5jdfH#IOYF*z|`F)$)5B5-MRV`w5eHZm+Cb97;HbYEg+
+zVRRxoI4(6TB4l-PVRUJ4ZeL<$VRUmMIxsFWH7p`_Wo&O_X>@raIxsFZEFy4WZX!A`
+zeJpz-X=EZgB5rSVWnXe-VRCX`F*i7WH8M0eH83zSIWb=`F(ND?aA|a7Xd*f`H!LD^
+zbYXIIUt(opbRs%9E;ltSB4l-PVRUJ4ZeL<$VRUmMIxsFWH7p`_Wo&O_X>@raIxsFY
+zEFy4WZX!A`eJpz-X=EZgB5rSVWnXe-VRCX`F*i6hGBh_eFfcJWF<&t<A}k_*aA|a7
+zXd*f_H7p`?bYXIIUt(opbRs%AEFxrea$$67Z*E^=Wnpx4B04ZGGBqqBc4cgDV`+4G
+zB04ZGHY_4=VQwNiFnuh0B57nIIwEdwbY)+1Wnpr1Uokg0H8M0eH83zSIWb=`Ga@V^
+zaA|a7Xd*f_IV>V`bYXIIUt(o{VRRxoIW96aEFxrea$$67Z*E^=Wnpx4B04ZGGBqqB
+zc4cgDV`+4GB04ZGH7p`<VQwNiFnuh0B57nIIwEdwbY)+1Wnpr1Uokg0H8M0eH83zS
+zIWb=`G$Je_aA|a7Xd*f`GAtr<bYXIIUt(opbRs%AE;TG7WOZ_3bZKt{0000DvjN}+
+lAQk`w0000G0000J0000I0000F0000FvjN}+AhRHF-Vfh6-aP;S
+
+diff --git a/app/templates/index.html b/app/templates/index.html
+index 1207348..5fa01fe 100644
+--- a/app/templates/index.html
++++ b/app/templates/index.html
+@@ -23,7 +23,7 @@
+     <script src="/static/js/services/midiExtractor.js?v=202607281052"></script>
+     <script src="/static/js/services/promptTemplateManager.js?v=202607281039"></script>
+     <script src="/static/js/services/audioMixerGraphManager.js?v=202607282218"></script>
+-    <script src="/static/js/app.precompiled.js?v=202607282359" defer></script>
++    <script src="/static/js/app.precompiled.js?v=20260729085936" defer></script>
+     <link rel="stylesheet" href="/static/css/styles.css?v=202607271016">
+     <style>
+         :root {
+-- 
+2.47.3
+
+diff --git a/app/static/js/app.jsx b/app/static/js/app.jsx
+index c53adde..8189c12 100644
+--- a/app/static/js/app.jsx
++++ b/app/static/js/app.jsx
+@@ -6025,7 +6025,7 @@ const PianoRollTabEditor = ({ st, zoom, bpm, viewportWidth, activeTracks, onClos
+             keybedMouseDownRef.current = true;
+             try {
+               if (window.SonicSF) {
+-                window.SonicSF.playNote(pitch, 100, 500, undefined, st.instrumentProgram, null, kbCh, kbSynth);
++                window.SonicSF.playNote(pitch, 100, 60000, undefined, st.instrumentProgram, null, kbCh, kbSynth);
+               }
+             } catch (err) {
+               console.error('playNote error:', err);
+@@ -6035,12 +6035,17 @@ const PianoRollTabEditor = ({ st, zoom, bpm, viewportWidth, activeTracks, onClos
+             if (keybedMouseDownRef.current) {
+               try {
+                 if (window.SonicSF) {
+-                  window.SonicSF.playNote(pitch, 100, 200, undefined, st.instrumentProgram, null, kbCh, kbSynth);
++                  window.SonicSF.playNote(pitch, 100, 60000, undefined, st.instrumentProgram, null, kbCh, kbSynth);
+                 }
+               } catch (err) { console.error('playNote error:', err); }
+             }
+           },
+-          onMouseUp: () => { keybedMouseDownRef.current = false; }
++          onMouseUp: () => {
++            keybedMouseDownRef.current = false;
++            if (window.SonicSF && window.SonicSF.stopNote) {
++              window.SonicSF.stopNote(kbCh, pitch);
++            }
++          }
+         }, showLabel && label)
+       );
+     }

package-lock.json

@@ -8,7 +8,41 @@
       "dependencies": {
         "@babel/cli": "^8.0.4",
         "@babel/core": "^8.0.1",
-        "@babel/preset-react": "^8.0.1"
+        "@babel/preset-react": "^8.0.1",
+        "jsdom": "^30.0.1",
+        "react": "^19.2.8",
+        "react-dom": "^19.2.8"
+      }
+    },
+    "node_modules/@asamuzakjp/css-color": {
+      "version": "6.0.5",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-6.0.5.tgz",
+      "integrity": "sha512-mbhpPMmnw/kwW19aRNmSUl1QzLbdGo1SCuE49BT98MNwqF6zaHb3o2owssFc/PEO/4t2UjqtCNwocuDtJornzA==",
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/css-calc": "^3.2.1",
+        "@csstools/css-color-parser": "^4.1.9",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0",
+        "lru-cache": "^11.5.2"
+      },
+      "engines": {
+        "node": "^22.13.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/dom-selector": {
+      "version": "8.3.0",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-8.3.0.tgz",
+      "integrity": "sha512-UJLfKXBhrc8i1vH2eJXuYQMwlsLKWFw3O+CPqXSuVEiikeAim3UgrfWX0k4tA/X8cRFM8iZ7OaqBokFGbYusdg==",
+      "license": "MIT",
+      "dependencies": {
+        "bidi-js": "^1.0.3",
+        "css-tree": "^3.2.1",
+        "is-potential-custom-element-name": "^1.0.1",
+        "lru-cache": "^11.5.2"
+      },
+      "engines": {
+        "node": "^22.13.0 || >=24.0.0"
       }
     },
     "node_modules/@babel/cli": {
@@ -366,6 +400,169 @@
         "node": "^22.18.0 || >=24.11.0"
       }
     },
+    "node_modules/@bramus/specificity": {
+      "version": "2.4.2",
+      "resolved": "https://registry.npmjs.org/@bramus/specificity/-/specificity-2.4.2.tgz",
+      "integrity": "sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==",
+      "license": "MIT",
+      "dependencies": {
+        "css-tree": "^3.0.0"
+      },
+      "bin": {
+        "specificity": "bin/cli.js"
+      }
+    },
+    "node_modules/@csstools/color-helpers": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-6.1.0.tgz",
+      "integrity": "sha512-064IFJdjTfUqnjpCVpMOdbr8FLQBhinbZj6yRv2An2E41O/pLEXqfFRWqGq/SxlE5PEUYTlvWsG2r8MswAVvkg==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.3.0.tgz",
+      "integrity": "sha512-c5ihYsPkdG6JCkU2zTMm4+k6r7RXuGxtWYhu5DHMIiF1FHzrfmHL5so11AoFpUv/tu61xfcmT4AmKoFfMPoqdQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "4.1.10",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.1.10.tgz",
+      "integrity": "sha512-UZhQLIUyJaaMepqehrCODwCg2KW25vFvLWBmqYFaPclYvvxzj/sG8LBOhBFCp11i9uE7t1EyS+RAoV9tztPFyw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/color-helpers": "^6.1.0",
+        "@csstools/css-calc": "^3.3.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-4.0.0.tgz",
+      "integrity": "sha512-+B87qS7fIG3L5h3qwJ/IFbjoVoOe/bpOdh9hAjXbvx0o8ImEmUsGXN0inFOnk2ChCFgqkkGFQ+TpM5rbhkKe4w==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-syntax-patches-for-csstree": {
+      "version": "1.1.7",
+      "resolved": "https://registry.npmjs.org/@csstools/css-syntax-patches-for-csstree/-/css-syntax-patches-for-csstree-1.1.7.tgz",
+      "integrity": "sha512-fQ+05118eQS1cofO3aJpB5efgpBZMvIzwr/sbC8kDLVA5XLG8q1kJV5yzrUAI1f7lvhPnm8fgIjzFB8/O/5Dig==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "peerDependencies": {
+        "css-tree": "^3.2.1"
+      },
+      "peerDependenciesMeta": {
+        "css-tree": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-4.0.0.tgz",
+      "integrity": "sha512-QxULHAm7cNu72w97JUNCBFODFaXpbDg+dP8b/oWFAZ2MTRppA3U00Y2L1HqaS4J6yBqxwa/Y3nMBaxVKbB/NsA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/@exodus/bytes": {
+      "version": "1.15.1",
+      "resolved": "https://registry.npmjs.org/@exodus/bytes/-/bytes-1.15.1.tgz",
+      "integrity": "sha512-S6mL0yNB/Abt9Ei4tq8gDhcczc4S3+vQ4ra7vxnAf+YHC02srtqxKKZghx2Dq6p0e66THKwR6r8N6P95wEty7Q==",
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "@noble/hashes": "^1.8.0 || ^2.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@noble/hashes": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@jridgewell/gen-mapping": {
       "version": "0.3.13",
       "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
@@ -434,6 +631,15 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/bidi-js": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.0.3.tgz",
+      "integrity": "sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==",
+      "license": "MIT",
+      "dependencies": {
+        "require-from-string": "^2.0.2"
+      }
+    },
     "node_modules/brace-expansion": {
       "version": "5.0.7",
       "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.7.tgz",
@@ -529,6 +735,52 @@
       "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
       "license": "MIT"
     },
+    "node_modules/css-tree": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.2.1.tgz",
+      "integrity": "sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA==",
+      "license": "MIT",
+      "dependencies": {
+        "mdn-data": "2.27.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0"
+      }
+    },
+    "node_modules/data-urls": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-7.0.0.tgz",
+      "integrity": "sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA==",
+      "license": "MIT",
+      "dependencies": {
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^16.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/data-urls/node_modules/whatwg-url": {
+      "version": "16.0.1",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-16.0.1.tgz",
+      "integrity": "sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==",
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.11.0",
+        "tr46": "^6.0.0",
+        "webidl-conversions": "^8.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/decimal.js": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
+      "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==",
+      "license": "MIT"
+    },
     "node_modules/electron-to-chromium": {
       "version": "1.5.393",
       "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.393.tgz",
@@ -544,6 +796,18 @@
         "node": ">=14"
       }
     },
+    "node_modules/entities": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-8.0.0.tgz",
+      "integrity": "sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/escalade": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
@@ -579,6 +843,18 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/html-encoding-sniffer": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-6.0.0.tgz",
+      "integrity": "sha512-CV9TW3Y3f8/wT0BRFc1/KAVQ3TUHiXmaAb6VW9vtiMFf7SLoMd1PdAc4W3KFOFETBJUb90KatHqlsZMWV+R9Gg==",
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.6.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
     "node_modules/import-meta-resolve": {
       "version": "4.2.0",
       "resolved": "https://registry.npmjs.org/import-meta-resolve/-/import-meta-resolve-4.2.0.tgz",
@@ -589,12 +865,58 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/is-potential-custom-element-name": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
+      "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
+      "license": "MIT"
+    },
     "node_modules/js-tokens": {
       "version": "10.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-10.0.0.tgz",
       "integrity": "sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==",
       "license": "MIT"
     },
+    "node_modules/jsdom": {
+      "version": "30.0.1",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-30.0.1.tgz",
+      "integrity": "sha512-52v7mUVUfNQVYYqE1lcdaymWL0njO7lTLUog6ZvW2U5KsbiLk/GnZlVJ+qx0xfNJZ6Gn+KSpPNE52vurbxZwrA==",
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/css-color": "^6.0.5",
+        "@asamuzakjp/dom-selector": "^8.3.0",
+        "@bramus/specificity": "^2.4.2",
+        "@csstools/css-syntax-patches-for-csstree": "^1.1.7",
+        "@exodus/bytes": "^1.15.1",
+        "css-tree": "^3.2.1",
+        "data-urls": "^7.0.0",
+        "decimal.js": "^10.6.0",
+        "html-encoding-sniffer": "^6.0.0",
+        "is-potential-custom-element-name": "^1.0.1",
+        "lru-cache": "^11.5.2",
+        "parse5": "^8.0.1",
+        "saxes": "^6.0.0",
+        "symbol-tree": "^3.2.4",
+        "tough-cookie": "^6.0.2",
+        "undici": "^8.9.0",
+        "w3c-xmlserializer": "^5.0.0",
+        "webidl-conversions": "^8.0.1",
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^17.1.0",
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      },
+      "peerDependencies": {
+        "canvas": "^3.2.3"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/jsesc": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
@@ -628,6 +950,12 @@
         "node": "20 || >=22"
       }
     },
+    "node_modules/mdn-data": {
+      "version": "2.27.1",
+      "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.27.1.tgz",
+      "integrity": "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==",
+      "license": "CC0-1.0"
+    },
     "node_modules/minimatch": {
       "version": "10.2.5",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz",
@@ -674,6 +1002,18 @@
         "node": ">=12.20.0"
       }
     },
+    "node_modules/parse5": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.1.tgz",
+      "integrity": "sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==",
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^8.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
     "node_modules/path-scurry": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz",
@@ -696,6 +1036,36 @@
       "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
       "license": "ISC"
     },
+    "node_modules/punycode": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
+      "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/react": {
+      "version": "19.2.8",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.2.8.tgz",
+      "integrity": "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "19.2.8",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.8.tgz",
+      "integrity": "sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ==",
+      "license": "MIT",
+      "dependencies": {
+        "scheduler": "^0.27.0"
+      },
+      "peerDependencies": {
+        "react": "^19.2.8"
+      }
+    },
     "node_modules/readdirp": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-5.0.0.tgz",
@@ -709,6 +1079,33 @@
         "url": "https://paulmillr.com/funding/"
       }
     },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/saxes": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
+      "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==",
+      "license": "ISC",
+      "dependencies": {
+        "xmlchars": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=v12.22.7"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.27.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz",
+      "integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==",
+      "license": "MIT"
+    },
     "node_modules/semver": {
       "version": "7.8.5",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
@@ -733,6 +1130,72 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/symbol-tree": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
+      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==",
+      "license": "MIT"
+    },
+    "node_modules/tldts": {
+      "version": "7.4.9",
+      "resolved": "https://registry.npmjs.org/tldts/-/tldts-7.4.9.tgz",
+      "integrity": "sha512-3kZ8wQQ/k5DrChD4X4FVvr2D7E5uoRgAqkPyLpSCGUvqOvqu+JEdr3mwMUaVWb+vMHZaKhF5fp2PBigKsui7hA==",
+      "license": "MIT",
+      "dependencies": {
+        "tldts-core": "^7.4.9"
+      },
+      "bin": {
+        "tldts": "bin/cli.js"
+      }
+    },
+    "node_modules/tldts-core": {
+      "version": "7.4.9",
+      "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-7.4.9.tgz",
+      "integrity": "sha512-DxKfPBI52p2msTEu7MPhdpdDTBhhVQg1a/8PjQckeyAvO13eMYElX545grIp6nnTGIMZlRvFZPvFhvI/WIz2Vg==",
+      "license": "MIT"
+    },
+    "node_modules/tough-cookie": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.0.2.tgz",
+      "integrity": "sha512-exgYmnmL/sJpR3upZfXG5PoatXQii55xAiXGXzY+sROLZ/Y+SLcp9PgJNI9Vz37HpQ74WvDcLT8eqm+kV3FzrA==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "tldts": "^7.0.5"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/tr46": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz",
+      "integrity": "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==",
+      "license": "MIT",
+      "dependencies": {
+        "punycode": "^2.3.1"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/undici": {
+      "version": "8.9.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-8.9.0.tgz",
+      "integrity": "sha512-aWZpUj7XoGonMClx4gdDRfgBjqeA+F473aDmROQQbM9n6PRfK/u1q/a0X4wMTgcHfT8H6fpbt98PFuDUwFg2YA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=22.19.0"
+      }
+    },
     "node_modules/update-browserslist-db": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
@@ -762,6 +1225,65 @@
       "peerDependencies": {
         "browserslist": ">= 4.21.0"
       }
+    },
+    "node_modules/w3c-xmlserializer": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
+      "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==",
+      "license": "MIT",
+      "dependencies": {
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/webidl-conversions": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz",
+      "integrity": "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-mimetype": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz",
+      "integrity": "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-url": {
+      "version": "17.1.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-17.1.0.tgz",
+      "integrity": "sha512-3GeworPmc2ZfEEHP7lEbUfBX/L75wdEsi0rLNhXcXxnoN5jyq0SL5gCy06SGW2cyTIZdTvWIDQNQoza++vKeaw==",
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.15.1",
+        "tr46": "^6.0.0",
+        "webidl-conversions": "^8.0.1"
+      },
+      "engines": {
+        "node": "^22.14.0 || >=24.0.0"
+      }
+    },
+    "node_modules/xml-name-validator": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
+      "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/xmlchars": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
+      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
+      "license": "MIT"
     }
   }
 }

package.json

@@ -7,6 +7,9 @@
   "dependencies": {
     "@babel/cli": "^8.0.4",
     "@babel/core": "^8.0.1",
-    "@babel/preset-react": "^8.0.1"
+    "@babel/preset-react": "^8.0.1",
+    "jsdom": "^30.0.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
   }
 }

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

soundfont_fix_backup_20260729_0941.patch

@@ -0,0 +1,24 @@
+diff --git a/app/static/js/services/soundfontPlayer.js b/app/static/js/services/soundfontPlayer.js
+index bb0a556..e85c936 100644
+--- a/app/static/js/services/soundfontPlayer.js
++++ b/app/static/js/services/soundfontPlayer.js
+@@ -130,6 +130,7 @@
+                     if (_useScriptNode) {
+                         var spBufSz = 2048;
+                         var spn = _audioCtx.createScriptProcessor(spBufSz, 0, 2);
++                        getCtx();
+                         var lp = _fluidModule._malloc(spBufSz * 4);
+                         var rp = _fluidModule._malloc(spBufSz * 4);
+                         spn.onaudioprocess = function (e) {
+@@ -151,6 +152,11 @@
+                         console.log("[SonicSF] ScriptProcessorNode fallback active (buf:", spBufSz, ")");
+                     }
+ 
++                    // Re-route through mixer graph if it exists (created before SonicSF was ready)
++                    if (window.__mixerGraphManager && typeof SonicSF.setOutputNode === 'function') {
++                        SonicSF.setOutputNode(window.__mixerGraphManager.masterGain);
++                    }
++
+                     _initialized = true;
+                     console.log("[SonicSF] FluidSynth WASM Engine initialized.");
+                 } catch (e) {

tests/conftest.py

@@ -0,0 +1,14 @@
+"""Pytest bootstrap: isolate the test suite from the development database.
+
+Must be imported before any app module (pytest imports conftest.py first), so
+app.models.user picks up the test DB path instead of the dev DB. Without this,
+tests that seed/rotate the admin password (test_auth_and_quota) permanently
+mutate the developer's sonicforge.db.
+"""
+import os
+import tempfile
+
+os.environ.setdefault(
+    "SONICFORGE_DB_PATH",
+    os.path.join(tempfile.gettempdir(), "sonicforge_test.db"),
+)

tests/test_ai_presets.py

@@ -0,0 +1,145 @@
+import os, json, time
+import pytest
+from fastapi.testclient import TestClient
+from app.main import app
+from app.config import settings
+from app.core.auth import create_token
+
+client = TestClient(app)
+
+TEST_DATA_FILE = os.path.join(settings.PROCESSED_DIR, "ai_presets.json")
+if os.path.exists(TEST_DATA_FILE):
+    os.remove(TEST_DATA_FILE)
+
+
+def _auth_header():
+    token = create_token("test_user_presets", "testuser", "standard", False)
+    return {"Authorization": f"Bearer {token}"}
+
+
+def test_list_presets_defaults():
+    res = client.get("/api/v1/ai/presets")
+    assert res.status_code == 200
+    data = res.json()
+    assert data["success"] is True
+    assert len(data["presets"]) == 7
+    names = [p["name"] for p in data["presets"]]
+    assert "Epic Orchestra Intro (8 Bars)" in names
+    assert "Pop Piano Chords (4 Bars)" in names
+    assert "Cyberpunk Synthwave (8 Bars)" in names
+    assert "Jazz Swing Variation" in names
+    assert "80s Synthwave Arpeggiator" in names
+
+
+def test_create_user_preset():
+    preset = {
+        "id": "preset_test_my_beat",
+        "name": "My Beat (4 Bars)",
+        "keywords": ["my beat", "custom beat", "beat của tôi"],
+        "category": "Hip Hop / Beat",
+        "default_bars": 4,
+        "default_bpm": 100,
+        "default_scale": "A Minor",
+        "system_instruction_template": "Generate a 4-bar hip hop beat with kick, snare, hi-hat.",
+        "is_user_defined": True,
+        "is_favorite": False,
+        "created_at": "2026-07-28T00:00:00Z"
+    }
+    res = client.post("/api/v1/ai/presets", json=preset, headers=_auth_header())
+    assert res.status_code == 200, res.text
+    data = res.json()
+    assert data["success"] is True
+    assert data["preset"]["id"] == "preset_test_my_beat"
+
+    # Verify it appears in listing
+    res2 = client.get("/api/v1/ai/presets", headers=_auth_header())
+    assert res2.status_code == 200
+    names = [p["name"] for p in res2.json()["presets"]]
+    assert "My Beat (4 Bars)" in names
+    assert len(res2.json()["presets"]) == 8  # 7 defaults + 1 user
+
+
+def test_update_user_preset():
+    preset = {
+        "id": "preset_test_my_beat",
+        "name": "My Beat Updated (8 Bars)",
+        "keywords": ["my beat", "custom beat"],
+        "category": "Hip Hop / Beat",
+        "default_bars": 8,
+        "default_bpm": 110,
+        "default_scale": "C Minor",
+        "system_instruction_template": "Generate an 8-bar hip hop beat.",
+        "is_user_defined": True,
+        "is_favorite": True,
+        "created_at": "2026-07-28T00:00:00Z"
+    }
+    res = client.post("/api/v1/ai/presets", json=preset, headers=_auth_header())
+    assert res.status_code == 200
+    data = res.json()
+    assert data["preset"]["name"] == "My Beat Updated (8 Bars)"
+    assert data["preset"]["is_favorite"] is True
+    assert data["preset"]["default_bars"] == 8
+
+
+def test_delete_user_preset():
+    res = client.delete("/api/v1/ai/presets/preset_test_my_beat", headers=_auth_header())
+    assert res.status_code == 200
+    data = res.json()
+    assert data["success"] is True
+
+    res2 = client.get("/api/v1/ai/presets", headers=_auth_header())
+    assert res2.status_code == 200
+    names = [p["name"] for p in res2.json()["presets"]]
+    assert "My Beat Updated (8 Bars)" not in names
+
+
+def test_delete_nonexistent_preset():
+    res = client.delete("/api/v1/ai/presets/nonexistent_id", headers=_auth_header())
+    assert res.status_code == 404
+
+
+def test_presets_anonymous_cannot_save():
+    preset = {
+        "id": "preset_anon",
+        "name": "Anon Preset",
+        "keywords": ["anon"],
+        "category": "General",
+        "default_bars": 4,
+        "default_bpm": 120,
+        "default_scale": "C Major",
+        "system_instruction_template": "Test",
+        "is_user_defined": True,
+        "is_favorite": False
+    }
+    res = client.post("/api/v1/ai/presets", json=preset)
+    assert res.status_code == 401
+
+    res2 = client.delete("/api/v1/ai/presets/preset_anon")
+    assert res2.status_code == 401
+
+
+def test_presets_isolation_between_users():
+    token_a = create_token("user_a", "usera", "standard", False)
+    token_b = create_token("user_b", "userb", "standard", False)
+
+    preset_a = {
+        "id": "preset_user_a_only",
+        "name": "User A Preset",
+        "keywords": ["user a"],
+        "category": "General",
+        "default_bars": 4,
+        "default_bpm": 120,
+        "default_scale": "C Major",
+        "system_instruction_template": "User A specific",
+        "is_user_defined": True,
+        "is_favorite": False
+    }
+    res = client.post("/api/v1/ai/presets", json=preset_a, headers={"Authorization": f"Bearer {token_a}"})
+    assert res.status_code == 200
+
+    # User B shouldn't see User A's presets
+    res_b = client.get("/api/v1/ai/presets", headers={"Authorization": f"Bearer {token_b}"})
+    assert res_b.status_code == 200
+    names_b = [p["name"] for p in res_b.json()["presets"]]
+    assert "User A Preset" not in names_b
+    assert "Epic Orchestra Intro (8 Bars)" in names_b

tests/test_ai_scan_dsp.py

@@ -1,5 +1,9 @@
 import pytest
 import numpy as np
+import os
+import app.api.v1.user_config as user_config
+user_config.DATA_FILE = os.path.join(os.path.dirname(__file__), "user_configs_test.json")
+
 from fastapi.testclient import TestClient
 from app.main import app
 from app.core.ai_dsp_engine import AIDSPEngine

tests/test_plugin_api.py

@@ -13,7 +13,17 @@ client = TestClient(app)
 def get_admin_token():
     resp = client.post("/api/v1/auth/login", json={"username": "admin", "password": "admin123"})
     if resp.status_code == 200:
-        return resp.json()["access_token"]
+        token = resp.json()["access_token"]
+        # Admin is seeded with must_change_password=1; the app blocks music
+        # processing until the first password change. Complete that flow here
+        # (keeping the same password) so feature tests run unblocked.
+        user = resp.json()["user"]
+        if user.get("must_change_password"):
+            r = client.post("/api/v1/auth/change-password", headers={"Authorization": f"Bearer {token}"},
+                            json={"old_password": "admin123", "new_password": "admin123"})
+            if r.status_code == 200:
+                token = r.json()["access_token"]
+        return token
     return None
 
 

tests/test_project_upgrade.py

@@ -0,0 +1,68 @@
+"""Regression tests for legacy project upgrade (items must stay on their tracks
+with correct bar positions)."""
+import json
+
+from app.api.v1.projects import upgrade_project_json_if_needed
+
+
+def _legacy_project():
+    return {
+        "id": "legacy_1",
+        "name": "Legacy",
+        "bpm": 120.0,  # 1 bar = 2.0s
+        "tracks": [
+            {
+                "id": "1",
+                "name": "Track 1",
+                "volumeDb": 0.0,
+                "pan": 0.0,
+                "muted": False,
+                "solo": False,
+                "serverFileId": "abc.wav",
+                "clips": [{"id": "c1", "name": "clip1", "startTime": 2.0}],
+                "midiItems": [],
+            },
+            {
+                "id": "2",
+                "name": "Track 2",
+                "volumeDb": 0.0,
+                "pan": 0.0,
+                "muted": False,
+                "solo": False,
+                "serverFileId": None,
+                "clips": [],
+                "midiItems": [
+                    {"id": "m1", "name": "midi1", "startTime": 4.0, "duration": 4.0,
+                     "notes": [{"id": "n1", "pitch": 60, "start_beat": 0.0, "duration_beats": 1.0, "velocity": 0.8}]}
+                ],
+            },
+        ],
+    }
+
+
+def test_upgrade_keeps_items_on_their_tracks():
+    upgraded = upgrade_project_json_if_needed(_legacy_project())
+    tracks = upgraded["main_session"]["tracks"]
+    assert len(tracks) == 2
+    t1_items = tracks[0]["items"]
+    t2_items = tracks[1]["items"]
+    # Items must NOT be merged into the first track
+    assert [i["type"] for i in t1_items] == ["AUDIO_ITEM"]
+    assert [i["type"] for i in t2_items] == ["MIDI_ITEM"]
+    assert t1_items[0]["id"] == "c1"
+    assert t2_items[0]["id"] == "m1"
+
+
+def test_upgrade_uses_bpm_based_seconds_per_bar():
+    upgraded = upgrade_project_json_if_needed(_legacy_project())
+    tracks = upgraded["main_session"]["tracks"]
+    # 120bpm -> 1 bar = 2.0s; clip at 2.0s -> start_bar 1.0
+    assert tracks[0]["items"][0]["start_bar"] == 1.0
+    # midi at 4.0s -> start_bar 2.0; duration 4.0s -> 2.0 bars
+    assert tracks[1]["items"][0]["start_bar"] == 2.0
+    assert tracks[1]["items"][0]["duration_bars"] == 2.0
+
+
+def test_upgrade_skips_new_format():
+    data = {"main_session": {"tracks": []}}
+    assert upgrade_project_json_if_needed(data) is data

tests/test_security_hardening.py

@@ -0,0 +1,234 @@
+"""Regression tests for security hardening.
+
+Covers the vulnerabilities found during the 2026-08 audit:
+- SSRF / open proxy on /api/v1/ai/proxy
+- path traversal on render output and audio file ids
+- unauthenticated filesystem access via /api/v1/media/*
+- hardcoded SECRET_KEY
+- quota bypass on project update
+- audio resampling correctness in the render engine
+"""
+import os
+import json
+
+import numpy as np
+import pytest
+import soundfile as sf
+from fastapi.testclient import TestClient
+
+from app.main import app
+from app.config import settings
+from app.core import auth as core_auth
+
+client = TestClient(app)
+
+
+def get_admin_token():
+    # test_auth_and_quota.py may have rotated the admin password; try both.
+    for pwd in ("admin123", "admin_new_password_2026"):
+        resp = client.post("/api/v1/auth/login", json={"username": "admin", "password": pwd})
+        if resp.status_code != 200:
+            continue
+        token = resp.json()["access_token"]
+        user = resp.json()["user"]
+        if user.get("must_change_password"):
+            r = client.post("/api/v1/auth/change-password", headers={"Authorization": f"Bearer {token}"},
+                            json={"old_password": pwd, "new_password": pwd})
+            if r.status_code == 200:
+                token = r.json()["access_token"]
+        return token
+    return None
+
+
+def auth_headers():
+    return {"Authorization": f"Bearer {get_admin_token()}"}
+
+
+# ── 1. SSRF / open proxy ──
+
+class TestAIProxySSRF:
+    def test_proxy_requires_auth(self):
+        resp = client.post("/api/v1/ai/proxy", json={"url": "https://api.openai.com/v1", "body": {}})
+        assert resp.status_code == 401
+
+    def test_proxy_blocks_cloud_metadata(self):
+        resp = client.post("/api/v1/ai/proxy", headers=auth_headers(),
+                           json={"url": "http://169.254.169.254/latest/meta-data/", "body": {}})
+        assert resp.status_code == 403
+
+    def test_proxy_blocks_private_ip_not_configured(self):
+        resp = client.post("/api/v1/ai/proxy", headers=auth_headers(),
+                           json={"url": "http://10.0.0.5/", "body": {}})
+        assert resp.status_code == 403
+
+    def test_proxy_rejects_non_http_scheme(self):
+        resp = client.post("/api/v1/ai/proxy", headers=auth_headers(),
+                           json={"url": "file:///etc/passwd", "body": {}})
+        assert resp.status_code == 400
+
+    def test_proxy_allows_configured_localhost_provider(self):
+        # localhost:11434 is in the default AI provider list; it must pass the
+        # SSRF check (and then fail to connect in this environment -> 502).
+        resp = client.post("/api/v1/ai/proxy", headers=auth_headers(),
+                           json={"url": "http://localhost:11434/v1/chat/completions", "body": {}})
+        assert resp.status_code == 502
+
+
+# ── 2. Path traversal ──
+
+class TestPathTraversal:
+    def test_render_output_filename_sanitized(self):
+        token = get_admin_token()
+        if not token:
+            pytest.skip("Cannot get admin token")
+        project = {
+            "metadata": {"bpm": 120, "time_signature_numerator": 4},
+            "main_session": {"length_bars": 1, "tracks": []},
+            "section_store": {},
+        }
+        resp = client.post("/api/v1/plugins/render", headers=auth_headers(),
+                           json={"project_json": project, "output_filename": "/tmp/evil_traversal.wav"})
+        # Absolute paths must be reduced to a basename inside PROCESSED_DIR.
+        assert resp.status_code == 200, resp.text
+        out_path = resp.json()["path"]
+        assert os.path.dirname(out_path) == settings.PROCESSED_DIR
+        assert os.path.basename(out_path) == "evil_traversal.wav"
+        assert os.path.isfile(out_path)
+
+    def test_audio_download_rejects_traversal(self):
+        resp = client.get("/api/v1/audio/download/..%2F..%2Fapp%2Fconfig.py")
+        assert resp.status_code == 404
+
+    def test_ai_scan_rejects_traversal_file_id(self):
+        resp = client.post("/api/v1/audio/ai-scan",
+                           json={"track_id": "1", "file_id": "../../app/config.py"})
+        # Traversal must NOT read the file: falls through to the demo branch.
+        assert resp.status_code == 200
+        assert resp.json()["success"] is True
+
+
+# ── 3. Filesystem exposure via media endpoints ──
+
+class TestMediaAuth:
+    # Use a fresh client (no cookies from earlier logins) to prove 401.
+    @pytest.fixture(autouse=True)
+    def _fresh_client(self):
+        self.fresh = TestClient(app)
+        yield
+        self.fresh.close()
+
+    def test_media_computer_requires_auth(self):
+        resp = self.fresh.get("/api/v1/media/computer")
+        assert resp.status_code == 401
+
+    def test_media_browse_requires_auth(self):
+        resp = self.fresh.get("/api/v1/media/browse", params={"path": "/etc"})
+        assert resp.status_code == 401
+
+    def test_media_file_requires_auth(self):
+        resp = self.fresh.get("/api/v1/media/file", params={"path": "/etc/passwd"})
+        assert resp.status_code == 401
+
+
+# ── 4. Secret key ──
+
+class TestSecretKey:
+    def test_secret_key_not_hardcoded_default(self):
+        assert core_auth.SECRET_KEY != "sonicforge_secret_key_super_secure_2026"
+        assert len(core_auth.SECRET_KEY) >= 32
+
+
+# ── 5. Quota enforcement on update ──
+
+class TestQuotaUpdate:
+    def test_update_cloud_project_enforces_quota(self):
+        token = get_admin_token()
+        if not token:
+            pytest.skip("Cannot get admin token")
+        # Register a fresh user with a small quota (unique name per run so the
+        # test is re-runnable against a persistent DB).
+        import uuid as _uuid
+        uname = f"quota_user_{_uuid.uuid4().hex[:8]}"
+        resp = client.post("/api/v1/auth/register", json={
+            "username": uname, "email": f"{uname}@studio.com", "password": "quota_pass_123"})
+        assert resp.status_code == 200, resp.text
+        user_token = resp.json()["access_token"]
+        user_headers = {"Authorization": f"Bearer {user_token}"}
+
+        # Shrink quota to 1 MB via admin API.
+        uid = resp.json()["user"]["id"]
+        r = client.put(f"/api/v1/admin/quotas/{uid}", headers=auth_headers(),
+                       json={"storage_limit_mb": 1, "max_tracks": 16})
+        assert r.status_code == 200, r.text
+
+        # Save a small project.
+        small = json.dumps({
+            "project_id": "p1",
+            "metadata": {"title": "small", "bpm": 120, "time_signature_numerator": 4,
+                         "time_signature_denominator": 4, "sample_rate": 44100},
+            "main_session": {"id": "main", "name": "MAIN SESSION", "is_root": True,
+                             "length_bars": 16.0, "auto_compute_length": True, "tracks": []},
+            "section_store": {}})
+        r = client.post("/api/v1/projects/cloud", headers=user_headers,
+                        json={"name": "small", "data_json": small})
+        assert r.status_code == 200, r.text
+        pid = r.json()["project_id"]
+
+        # Updating with a payload over the quota must be rejected (was a bypass).
+        items = [{
+            "type": "AUDIO_ITEM", "id": f"it_{i}", "name": "n",
+            "start_bar": 0.0, "duration_bars": 1.0, "clip_start_offset_bars": 0.0,
+            "source_data": {"audio_file_url": "", "gain": 1.0},
+        } for i in range(20000)]
+        huge = json.dumps({
+            "project_id": "p1",
+            "metadata": {"title": "huge", "bpm": 120, "time_signature_numerator": 4,
+                         "time_signature_denominator": 4, "sample_rate": 44100},
+            "main_session": {"id": "main", "name": "MAIN SESSION", "is_root": True,
+                             "length_bars": 16.0, "auto_compute_length": True,
+                             "tracks": [{"id": "t", "name": "x", "type": "AUDIO", "items": items}]},
+            "section_store": {}})
+        r = client.put(f"/api/v1/projects/cloud/{pid}", headers=user_headers,
+                       json={"name": "huge", "data_json": huge})
+        assert r.status_code == 400, r.text
+        assert "Quota" in r.json()["detail"]
+
+
+# ── 6. Render engine: resampling correctness ──
+
+class TestRenderResample:
+    def test_audio_item_resampled_to_engine_rate(self, tmp_path):
+        from app.core.render_engine import PythonRenderEngine
+        # 44.1kHz source, engine at 22.05kHz -> exactly 2x downsampling.
+        sr_src = 44100
+        t = np.arange(sr_src) / sr_src
+        tone = (0.5 * np.sin(2 * np.pi * 440 * t)).astype(np.float32)
+        src_path = os.path.join(settings.UPLOADS_DIR, "resample_test_tone.wav")
+        sf.write(src_path, tone, sr_src)
+
+        engine = PythonRenderEngine(sample_rate=22050)
+        session = {
+            "tracks": [{
+                "type": "AUDIO",
+                "volume_db": 0.0, "pan": 0.0, "mute": False,
+                "items": [{
+                    "type": "AUDIO_ITEM",
+                    "start_bar": 0.0, "duration_bars": 4.0,
+                    "clip_start_offset_bars": 0.0,
+                    "source_data": {"audio_file_url": "/static/audio/uploads/resample_test_tone.wav", "gain": 1.0},
+                }],
+            }]
+        }
+        buf = engine.render_session_container(session, {}, bpm=120.0, time_sig_num=4,
+                                              total_samples=engine.sample_rate * 2)
+        # A 1s 440Hz tone must actually render energy (previously the SR
+        # mismatch silently skipped the audio).
+        assert np.max(np.abs(buf)) > 0.01
+        # Duration should be ~1 second at the engine rate, not 2.
+        nonzero = np.where(np.abs(buf[0]) > 1e-4)[0]
+        assert len(nonzero) > 0
+        assert (nonzero[-1] - nonzero[0]) < int(engine.sample_rate * 1.3)
+        try:
+            os.remove(src_path)
+        except OSError:
+            pass

tests/user_configs_test.json

@@ -0,0 +1,47 @@
+{
+  "ai_configs": {
+    "anonymous": [
+      {
+        "id": "openai_default",
+        "name": "OpenAI Official",
+        "provider_type": "openai",
+        "api_base_url": "https://api.openai.com/v1",
+        "api_key": "test-sk-key-123",
+        "model_name": "gpt-4o",
+        "temperature": 0.7,
+        "is_active": true
+      },
+      {
+        "id": "openai_compat_default",
+        "name": "OpenAI Compatible (Ollama/LocalAI/DeepSeek)",
+        "provider_type": "openai_compatible",
+        "api_base_url": "http://localhost:11434/v1",
+        "api_key": "ollama",
+        "model_name": "deepseek-r1",
+        "temperature": 0.7,
+        "is_active": false
+      },
+      {
+        "id": "anthropic_default",
+        "name": "Anthropic Claude",
+        "provider_type": "anthropic",
+        "api_base_url": "https://api.anthropic.com/v1",
+        "api_key": "",
+        "model_name": "claude-3-5-sonnet",
+        "temperature": 0.7,
+        "is_active": false
+      },
+      {
+        "id": "gemini_default",
+        "name": "Google Gemini",
+        "provider_type": "gemini",
+        "api_base_url": "https://generativelanguage.googleapis.com",
+        "api_key": "",
+        "model_name": "gemini-1.5-pro",
+        "temperature": 0.7,
+        "is_active": false
+      }
+    ]
+  },
+  "preferences": {}
+}

tools/cloud_projects_backup.json

@@ -0,0 +1,993 @@
+[
+  {
+    "id": "bca1bb5f-b656-48a8-b113-8fff900188ab",
+    "name": "Test",
+    "data_json": {
+      "project_id": "project_1784710097790",
+      "metadata": {
+        "title": "Test",
+        "bpm": 120.0,
+        "time_signature_numerator": 4,
+        "time_signature_denominator": 4,
+        "sample_rate": 44100
+      },
+      "main_session": {
+        "id": "main",
+        "name": "MAIN SESSION",
+        "is_root": true,
+        "length_bars": 16.0,
+        "auto_compute_length": true,
+        "tracks": [
+          {
+            "id": "1",
+            "name": "Track 01",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "fx_chain": [],
+            "synth_engine": {
+              "plugin_id": "synth",
+              "preset_id": "default",
+              "parameters": {}
+            },
+            "items": []
+          },
+          {
+            "id": "2",
+            "name": "Track 02",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "fx_chain": [],
+            "synth_engine": {
+              "plugin_id": "synth",
+              "preset_id": "default",
+              "parameters": {}
+            },
+            "items": []
+          }
+        ]
+      },
+      "section_store": {}
+    },
+    "updated_at": 1784710143.4476569
+  },
+  {
+    "id": "d627f532-b632-4ef0-a21f-80dcc2ac8396",
+    "name": "Test",
+    "data_json": {
+      "project_id": "project_1784719724178",
+      "metadata": {
+        "title": "Test",
+        "bpm": 120.0,
+        "time_signature_numerator": 4,
+        "time_signature_denominator": 4,
+        "sample_rate": 44100
+      },
+      "main_session": {
+        "id": "main",
+        "name": "MAIN SESSION",
+        "is_root": true,
+        "length_bars": 16.0,
+        "auto_compute_length": true,
+        "tracks": [
+          {
+            "id": "1",
+            "name": "Track 01",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "fx_chain": [],
+            "synth_engine": {
+              "plugin_id": "synth",
+              "preset_id": "default",
+              "parameters": {}
+            },
+            "items": []
+          },
+          {
+            "id": "2",
+            "name": "Track 02",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "fx_chain": [],
+            "synth_engine": {
+              "plugin_id": "synth",
+              "preset_id": "default",
+              "parameters": {}
+            },
+            "items": []
+          }
+        ]
+      },
+      "section_store": {}
+    },
+    "updated_at": 1784719770.23144
+  },
+  {
+    "id": "a17fe50b-c51d-408d-b45c-c09645777e68",
+    "name": "Test",
+    "data_json": {
+      "project_id": "project_1784719775936",
+      "metadata": {
+        "title": "Test",
+        "bpm": 120.0,
+        "time_signature_numerator": 4,
+        "time_signature_denominator": 4,
+        "sample_rate": 44100
+      },
+      "main_session": {
+        "id": "main",
+        "name": "MAIN SESSION",
+        "is_root": true,
+        "length_bars": 16.0,
+        "auto_compute_length": true,
+        "tracks": [
+          {
+            "id": "1",
+            "name": "Track 01",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "fx_chain": [],
+            "synth_engine": {
+              "plugin_id": "synth",
+              "preset_id": "default",
+              "parameters": {}
+            },
+            "items": []
+          },
+          {
+            "id": "2",
+            "name": "Track 02",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "fx_chain": [],
+            "synth_engine": {
+              "plugin_id": "synth",
+              "preset_id": "default",
+              "parameters": {}
+            },
+            "items": []
+          }
+        ]
+      },
+      "section_store": {}
+    },
+    "updated_at": 1784719821.9856758
+  },
+  {
+    "id": "38a0f344-05dc-47e3-a769-07426c57f5fe",
+    "name": "Test",
+    "data_json": {
+      "project_id": "project_1784720540893",
+      "metadata": {
+        "title": "Test",
+        "bpm": 120.0,
+        "time_signature_numerator": 4,
+        "time_signature_denominator": 4,
+        "sample_rate": 44100
+      },
+      "main_session": {
+        "id": "main",
+        "name": "MAIN SESSION",
+        "is_root": true,
+        "length_bars": 16.0,
+        "auto_compute_length": true,
+        "tracks": [
+          {
+            "id": "1",
+            "name": "Cartoon Capers Loop.mp3",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "fx_chain": [],
+            "synth_engine": {
+              "plugin_id": "synth",
+              "preset_id": "default",
+              "parameters": {}
+            },
+            "items": []
+          },
+          {
+            "id": "2",
+            "name": "Track 02",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "fx_chain": [],
+            "synth_engine": {
+              "plugin_id": "synth",
+              "preset_id": "default",
+              "parameters": {}
+            },
+            "items": []
+          }
+        ]
+      },
+      "section_store": {}
+    },
+    "updated_at": 1784720586.9746954
+  },
+  {
+    "id": "8037d8f5-1410-4639-8167-5b89dcb1c3e9",
+    "name": "Rose",
+    "data_json": {
+      "project_id": "project_1784720555735",
+      "metadata": {
+        "title": "Rose",
+        "bpm": 120.0,
+        "time_signature_numerator": 4,
+        "time_signature_denominator": 4,
+        "sample_rate": 44100
+      },
+      "main_session": {
+        "id": "main",
+        "name": "MAIN SESSION",
+        "is_root": true,
+        "length_bars": 16.0,
+        "auto_compute_length": true,
+        "tracks": [
+          {
+            "id": "1",
+            "name": "Track 01",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "fx_chain": [],
+            "synth_engine": {
+              "plugin_id": "synth",
+              "preset_id": "default",
+              "parameters": {}
+            },
+            "items": []
+          },
+          {
+            "id": "2",
+            "name": "Track 02",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "fx_chain": [],
+            "synth_engine": {
+              "plugin_id": "synth",
+              "preset_id": "default",
+              "parameters": {}
+            },
+            "items": []
+          }
+        ]
+      },
+      "section_store": {}
+    },
+    "updated_at": 1784720601.8155787
+  },
+  {
+    "id": "525bdab5-e594-4a0c-a3e6-102a0abef816",
+    "name": "Rose (autosave 03/08)",
+    "data_json": {
+      "project_id": "8037d8f5-1410-4639-8167-5b89dcb1c3e9",
+      "metadata": {
+        "title": "Rose (autosave 03/08)",
+        "bpm": 128,
+        "time_signature_numerator": 4,
+        "time_signature_denominator": 4,
+        "sample_rate": 44100
+      },
+      "main_session": {
+        "id": "main",
+        "name": "MAIN SESSION",
+        "is_root": true,
+        "length_bars": 16,
+        "auto_compute_length": true,
+        "tracks": [
+          {
+            "id": "1",
+            "name": "Track 01",
+            "type": "MIDI",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "instrument_id": "sf_DSK_Asian_DreamZ",
+            "instrument_program": 5,
+            "instrument_name": "BAN-DI",
+            "items": [
+              {
+                "id": "midi_1785057918746",
+                "name": "MIDI Item",
+                "type": "MIDI_ITEM",
+                "start_bar": 0,
+                "duration_bars": 4,
+                "clip_start_offset_bars": 0,
+                "source_data": {
+                  "total_buffer_bars": 4,
+                  "notes": [
+                    {
+                      "id": "note_1785057946413j2a54",
+                      "pitch": 55,
+                      "start_beat": 1.5,
+                      "duration_beats": 0.125,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946488uv1f6r6q_2",
+                      "pitch": 56,
+                      "start_beat": 1.5166666666666666,
+                      "duration_beats": 0.2333333333333334,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946505gxl5rre2_3",
+                      "pitch": 57,
+                      "start_beat": 1.75,
+                      "duration_beats": 0.3833333333333333,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946522v0dmipvj_4",
+                      "pitch": 60,
+                      "start_beat": 2.1333333333333333,
+                      "duration_beats": 0.2666666666666666,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_17850579465381vqpeamx_5",
+                      "pitch": 62,
+                      "start_beat": 2.4,
+                      "duration_beats": 0.21666666666666679,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946555rmpgksfp_6",
+                      "pitch": 63,
+                      "start_beat": 2.6166666666666667,
+                      "duration_beats": 0.20000000000000018,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946572cvrxri09_7",
+                      "pitch": 64,
+                      "start_beat": 2.816666666666667,
+                      "duration_beats": 0.25,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946588nvmp7zld_8",
+                      "pitch": 66,
+                      "start_beat": 3.066666666666667,
+                      "duration_beats": 0.1499999999999999,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946605jkbnh8mf_9",
+                      "pitch": 67,
+                      "start_beat": 3.216666666666667,
+                      "duration_beats": 0.2666666666666666,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946638i28svktt_10",
+                      "pitch": 68,
+                      "start_beat": 3.4833333333333334,
+                      "duration_beats": 0.1499999999999999,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_17850579466559iy45ml8_11",
+                      "pitch": 69,
+                      "start_beat": 3.6333333333333333,
+                      "duration_beats": 0.1333333333333333,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946672s712j5m6_12",
+                      "pitch": 70,
+                      "start_beat": 3.7666666666666666,
+                      "duration_beats": 0.1333333333333333,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946688pq858zcx_13",
+                      "pitch": 71,
+                      "start_beat": 3.9,
+                      "duration_beats": 0.18333333333333313,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_17850579467054usc79tx_14",
+                      "pitch": 72,
+                      "start_beat": 4.083333333333333,
+                      "duration_beats": 0.15000000000000036,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946722dspmlfaa_15",
+                      "pitch": 73,
+                      "start_beat": 4.233333333333333,
+                      "duration_beats": 0.2999999999999998,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946755h5mvip3h_16",
+                      "pitch": 74,
+                      "start_beat": 4.533333333333333,
+                      "duration_beats": 0.15000000000000036,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946772a5e5iona_17",
+                      "pitch": 75,
+                      "start_beat": 4.683333333333334,
+                      "duration_beats": 0.16666666666666607,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946788cfqxk2c8_18",
+                      "pitch": 76,
+                      "start_beat": 4.85,
+                      "duration_beats": 0.2666666666666666,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_178505794682247xy477z_19",
+                      "pitch": 77,
+                      "start_beat": 5.116666666666666,
+                      "duration_beats": 0.25,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946855nygukqis_20",
+                      "pitch": 78,
+                      "start_beat": 5.366666666666666,
+                      "duration_beats": 0.20000000000000018,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057946888oyfvmvq2_21",
+                      "pitch": 79,
+                      "start_beat": 5.566666666666666,
+                      "duration_beats": 0.35000000000000053,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947455xrq7rfmm_22",
+                      "pitch": 78,
+                      "start_beat": 5.916666666666667,
+                      "duration_beats": 0.2833333333333332,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_17850579474722sn8bsed_23",
+                      "pitch": 77,
+                      "start_beat": 6.2,
+                      "duration_beats": 0.31666666666666643,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947489mbv5z7q6_24",
+                      "pitch": 76,
+                      "start_beat": 6.516666666666667,
+                      "duration_beats": 0.2833333333333332,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947505qmasllso_25",
+                      "pitch": 75,
+                      "start_beat": 6.8,
+                      "duration_beats": 0.41666666666666696,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947539wkqyr6fw_26",
+                      "pitch": 74,
+                      "start_beat": 7.216666666666667,
+                      "duration_beats": 0.18333333333333357,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947572a2ydjwzu_27",
+                      "pitch": 73,
+                      "start_beat": 7.4,
+                      "duration_beats": 0.1999999999999993,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947589b18pcser_28",
+                      "pitch": 72,
+                      "start_beat": 7.6,
+                      "duration_beats": 0.16666666666666696,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947605bsiv751r_29",
+                      "pitch": 71,
+                      "start_beat": 7.766666666666667,
+                      "duration_beats": 0.13333333333333375,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947622ii453i6x_30",
+                      "pitch": 70,
+                      "start_beat": 7.9,
+                      "duration_beats": 0.18333333333333357,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947639zdv6seea_31",
+                      "pitch": 69,
+                      "start_beat": 8.083333333333334,
+                      "duration_beats": 0.36666666666666536,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947672devle9p7_32",
+                      "pitch": 68,
+                      "start_beat": 8.45,
+                      "duration_beats": 0.25,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947689x8rgn7ih_33",
+                      "pitch": 67,
+                      "start_beat": 8.7,
+                      "duration_beats": 0.3333333333333339,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947722u5b36hrl_34",
+                      "pitch": 66,
+                      "start_beat": 9.033333333333333,
+                      "duration_beats": 0.2833333333333332,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947772f9qp4st0_35",
+                      "pitch": 65,
+                      "start_beat": 9.316666666666666,
+                      "duration_beats": 0.38333333333333286,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947805cf5bjiv1_36",
+                      "pitch": 64,
+                      "start_beat": 9.7,
+                      "duration_beats": 0.6666666666666679,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947855ojfcoccj_37",
+                      "pitch": 63,
+                      "start_beat": 10.366666666666667,
+                      "duration_beats": 0.36666666666666536,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_17850579478721jvhzolj_38",
+                      "pitch": 62,
+                      "start_beat": 10.733333333333333,
+                      "duration_beats": 0.3000000000000007,
+                      "velocity": 0.8,
+                      "pan": 0
+                    },
+                    {
+                      "id": "note_1785057947889nqk9ckue_39",
+                      "pitch": 61,
+                      "start_beat": 11.033333333333333,
+                      "duration_beats": 0.3333333333333339,
+                      "velocity": 0.8,
+                      "pan": 0
+                    }
+                  ]
+                }
+              }
+            ]
+          },
+          {
+            "id": "2",
+            "name": "Track 02",
+            "type": "AUDIO",
+            "volume_db": 0,
+            "pan": 0,
+            "mute": false,
+            "solo": false,
+            "instrument_id": null,
+            "instrument_program": null,
+            "instrument_name": null,
+            "items": []
+          }
+        ]
+      },
+      "sub_tabs": [
+        {
+          "id": "midi_1785057919362",
+          "label": "Piano Roll: MIDI Item",
+          "type": "PIANO_ROLL",
+          "track_id": "1",
+          "target_id": "midi_1785057918746",
+          "parent_tab_id": null,
+          "notes": [
+            {
+              "id": "note_1785057946413j2a54",
+              "pitch": 55,
+              "start_beat": 1.5,
+              "duration_beats": 0.125,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946488uv1f6r6q_2",
+              "pitch": 56,
+              "start_beat": 1.5166666666666666,
+              "duration_beats": 0.2333333333333334,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946505gxl5rre2_3",
+              "pitch": 57,
+              "start_beat": 1.75,
+              "duration_beats": 0.3833333333333333,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946522v0dmipvj_4",
+              "pitch": 60,
+              "start_beat": 2.1333333333333333,
+              "duration_beats": 0.2666666666666666,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_17850579465381vqpeamx_5",
+              "pitch": 62,
+              "start_beat": 2.4,
+              "duration_beats": 0.21666666666666679,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946555rmpgksfp_6",
+              "pitch": 63,
+              "start_beat": 2.6166666666666667,
+              "duration_beats": 0.20000000000000018,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946572cvrxri09_7",
+              "pitch": 64,
+              "start_beat": 2.816666666666667,
+              "duration_beats": 0.25,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946588nvmp7zld_8",
+              "pitch": 66,
+              "start_beat": 3.066666666666667,
+              "duration_beats": 0.1499999999999999,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946605jkbnh8mf_9",
+              "pitch": 67,
+              "start_beat": 3.216666666666667,
+              "duration_beats": 0.2666666666666666,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946638i28svktt_10",
+              "pitch": 68,
+              "start_beat": 3.4833333333333334,
+              "duration_beats": 0.1499999999999999,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_17850579466559iy45ml8_11",
+              "pitch": 69,
+              "start_beat": 3.6333333333333333,
+              "duration_beats": 0.1333333333333333,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946672s712j5m6_12",
+              "pitch": 70,
+              "start_beat": 3.7666666666666666,
+              "duration_beats": 0.1333333333333333,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946688pq858zcx_13",
+              "pitch": 71,
+              "start_beat": 3.9,
+              "duration_beats": 0.18333333333333313,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_17850579467054usc79tx_14",
+              "pitch": 72,
+              "start_beat": 4.083333333333333,
+              "duration_beats": 0.15000000000000036,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946722dspmlfaa_15",
+              "pitch": 73,
+              "start_beat": 4.233333333333333,
+              "duration_beats": 0.2999999999999998,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946755h5mvip3h_16",
+              "pitch": 74,
+              "start_beat": 4.533333333333333,
+              "duration_beats": 0.15000000000000036,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946772a5e5iona_17",
+              "pitch": 75,
+              "start_beat": 4.683333333333334,
+              "duration_beats": 0.16666666666666607,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946788cfqxk2c8_18",
+              "pitch": 76,
+              "start_beat": 4.85,
+              "duration_beats": 0.2666666666666666,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_178505794682247xy477z_19",
+              "pitch": 77,
+              "start_beat": 5.116666666666666,
+              "duration_beats": 0.25,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946855nygukqis_20",
+              "pitch": 78,
+              "start_beat": 5.366666666666666,
+              "duration_beats": 0.20000000000000018,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057946888oyfvmvq2_21",
+              "pitch": 79,
+              "start_beat": 5.566666666666666,
+              "duration_beats": 0.35000000000000053,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947455xrq7rfmm_22",
+              "pitch": 78,
+              "start_beat": 5.916666666666667,
+              "duration_beats": 0.2833333333333332,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_17850579474722sn8bsed_23",
+              "pitch": 77,
+              "start_beat": 6.2,
+              "duration_beats": 0.31666666666666643,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947489mbv5z7q6_24",
+              "pitch": 76,
+              "start_beat": 6.516666666666667,
+              "duration_beats": 0.2833333333333332,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947505qmasllso_25",
+              "pitch": 75,
+              "start_beat": 6.8,
+              "duration_beats": 0.41666666666666696,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947539wkqyr6fw_26",
+              "pitch": 74,
+              "start_beat": 7.216666666666667,
+              "duration_beats": 0.18333333333333357,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947572a2ydjwzu_27",
+              "pitch": 73,
+              "start_beat": 7.4,
+              "duration_beats": 0.1999999999999993,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947589b18pcser_28",
+              "pitch": 72,
+              "start_beat": 7.6,
+              "duration_beats": 0.16666666666666696,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947605bsiv751r_29",
+              "pitch": 71,
+              "start_beat": 7.766666666666667,
+              "duration_beats": 0.13333333333333375,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947622ii453i6x_30",
+              "pitch": 70,
+              "start_beat": 7.9,
+              "duration_beats": 0.18333333333333357,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947639zdv6seea_31",
+              "pitch": 69,
+              "start_beat": 8.083333333333334,
+              "duration_beats": 0.36666666666666536,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947672devle9p7_32",
+              "pitch": 68,
+              "start_beat": 8.45,
+              "duration_beats": 0.25,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947689x8rgn7ih_33",
+              "pitch": 67,
+              "start_beat": 8.7,
+              "duration_beats": 0.3333333333333339,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947722u5b36hrl_34",
+              "pitch": 66,
+              "start_beat": 9.033333333333333,
+              "duration_beats": 0.2833333333333332,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947772f9qp4st0_35",
+              "pitch": 65,
+              "start_beat": 9.316666666666666,
+              "duration_beats": 0.38333333333333286,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947805cf5bjiv1_36",
+              "pitch": 64,
+              "start_beat": 9.7,
+              "duration_beats": 0.6666666666666679,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947855ojfcoccj_37",
+              "pitch": 63,
+              "start_beat": 10.366666666666667,
+              "duration_beats": 0.36666666666666536,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_17850579478721jvhzolj_38",
+              "pitch": 62,
+              "start_beat": 10.733333333333333,
+              "duration_beats": 0.3000000000000007,
+              "velocity": 0.8,
+              "pan": 0
+            },
+            {
+              "id": "note_1785057947889nqk9ckue_39",
+              "pitch": 61,
+              "start_beat": 11.033333333333333,
+              "duration_beats": 0.3333333333333339,
+              "velocity": 0.8,
+              "pan": 0
+            }
+          ],
+          "duration": 7.5,
+          "instrument_program": 5,
+          "instrument_name": "BAN-DI",
+          "current_time": 0,
+          "color": null
+        }
+      ],
+      "section_store": {}
+    },
+    "updated_at": 1785058087.45
+  }
+]

tools/restore_cloud_projects.py

@@ -0,0 +1,62 @@
+"""Khôi phục các dự án cloud cũ (từ git history) vào bất kỳ sonicforge.db nào.
+
+Cách dùng trên máy deployment thật (host game):
+    python3 tools/restore_cloud_projects.py /path/to/sonicforge.db
+
+Script đọc backup projects (JSON) đã xuất từ git history và chèn vào DB chỉ định,
+gán tất cả cho user_id được yêu cầu (mặc định: admin đầu tiên tìm thấy).
+"""
+import json
+import os
+import sqlite3
+import sys
+
+PROJECTS_BACKUP = os.path.join(os.path.dirname(__file__), "cloud_projects_backup.json")
+
+
+def main(db_path: str, user_id: str = None):
+    if not os.path.exists(PROJECTS_BACKUP):
+        print(f"Không tìm thấy {PROJECTS_BACKUP}")
+        return 1
+    if not os.path.exists(db_path):
+        print(f"Không tìm thấy DB: {db_path}")
+        return 1
+
+    with open(PROJECTS_BACKUP) as f:
+        projects = json.load(f)
+
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+
+    if user_id is None:
+        row = conn.execute("SELECT id FROM users WHERE role='admin' ORDER BY created_at LIMIT 1").fetchone()
+        if not row:
+            print("Không có user admin nào trong DB")
+            conn.close()
+            return 1
+        user_id = row["id"]
+        print(f"Gán tất cả cho admin: {user_id}")
+
+    restored = 0
+    for p in projects:
+        if conn.execute("SELECT id FROM projects WHERE id=?", (p["id"],)).fetchone():
+            print(f"  bỏ qua (đã tồn tại): {p['name']}")
+            continue
+        conn.execute(
+            "INSERT INTO projects (id, user_id, name, data_json, is_temp, size_bytes, updated_at) VALUES (?,?,?,?,0,?,?)",
+            (p["id"], user_id, p["name"], json.dumps(p["data_json"], ensure_ascii=False),
+             len(json.dumps(p["data_json"]).encode("utf-8")), p["updated_at"]))
+        restored += 1
+        print(f"  đã khôi phục: {p['name']}")
+
+    conn.commit()
+    conn.close()
+    print(f"\nHoàn tất: {restored} dự án đã khôi phục cho user {user_id}")
+    return 0
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python3 restore_cloud_projects.py <path/to/sonicforge.db> [user_id]")
+        sys.exit(1)
+    sys.exit(main(sys.argv[1], sys.argv[2] if len(sys.argv) > 2 else None))