SonicForgeStudio/PLAN_MASTERBUS_VST_GUI_EMBED.md

# PLAN: Nhúng native VST FX GUI vào Mastering Panel + FX Rack Panel

Ngày: 2026-08-17
Trạng thái: LINUX PHẦN HOÀN THÀNH (0L1, 0L2, 1L1, 2L1, 3L1, 4L1) — commit
`<pending>`; WINDOWS PHẦN CÒN LẠI (0W1, 0W2, 1W1, 2W1, 3W1, 4W1) — làm theo
`WALKTHROUGH_WINDOWS.md`. Tách task: `TASKS_LINUX_WINDOWS.md`.
Kế thừa: `PLAN_MASTERBUS_FX_RACK_VST.md` Phase 0-3 HOÀN THÀNH (commit
`b261eb0` render FX, `38f4cbd` mở native VST GUI dạng cửa sổ rời qua
`--open-fx-gui`).

## 1. Mục tiêu

Hoàn thiện vòng đời VST FX trong **MASTERING PANEL** (`MasteringModal`) và
**FX RACK PANEL** (`FXRackModal`):

1. **Nút X trên slot plugin** → xóa plugin khỏi ô slot.
   → **ĐÃ CÓ** (`removeVst`/`removeMasterVst` + `<button>` X trong `vstRow`,
   `app/static/js/app.jsx:11757`). Chỉ xác minh, không code lại.
2. **Nút +** → thêm VST trực tiếp vào panel VÀ **load native VST GUI ngay
   trong panel** — thay vì cửa sổ rời như hiện tại (`SonicAPI.openFxGui` →
   bridge `--open-fx-gui` mở window 800x600 tách biệt).
3. **Đóng GUI** → panel trở về graph GUI. **Click slot VST đã load** → mở lại
   GUI nhúng, **thay thế vùng graph GUI của panel** bằng native VST GUI ở đó.

## 2. Hiện trạng

| Hạng mục | Hiện tại | Delta cần |
|---|---|---|
| Slot VST masterbus | `masterVstChain` (`vstFxChain`) + `vstRow` | giữ |
| Slot VST per-track | `track.vstFxChain` + `vstRow` | giữ |
| Nút X xóa slot | có (`removeV*`) | xác minh |
| Nút + thêm + mở GUI | có (`addVst`/`addMasterVst` → `openVstGui`/`openMasterVstGui`) | **đổi từ cửa sổ rời → GUI nhúng trong panel** |
| GUI mở | bridge `--open-fx-gui` (RenderFxJob.cpp:889+, `FxGuiWndProc`, `fxGuiAttachSafe`, IPlugView attach HWND) | giữ làm nền, thêm capture + input relay |
| Graph GUI của panel | MasteringModal: vùng canvas EQ/imager/meters (`eqCanvasRef`…); FXRackModal: `scopeCanvasRef`/`eqCurveRef` | vùng này bị thay thế khi GUI mở |
| Tauri | src-tauri v2 có, app cũng chạy qua LAN browser | GUI nhúng phải chạy cả 2 môi trường → không dùng overlay native window |

**Quyết định kiến trúc:** app là web (browser/Tauri webview) → không thể nhúng
HWND trực tiếp. Dùng **frame-capture + input relay** (kiểu VNC cho plugin
window): bridge giữ native editor window, chụp bitmap → HTTP, frontend hiển
thị trong panel và gửi pointer/key về bridge → `SendMessage` tới HWND plugin.

## 3. Kiến trúc đích

### 3.1. Bridge: mode `--fx-gui <job.json>` (C++, Windows, MIT)

Mở rộng từ `--open-fx-gui` hiện có (giữ nguyên phần attach IPlugView):

- Sau khi attach view (đã có `fxGuiAttachSafe`), chạy **HTTP server mini**
  (port ngẫu nhiên, ghi vào job output/stdout để Python đọc):
  - `GET /frame` → PNG/JPEG chụp từ HWND plugin bằng `BitBlt` (fallback
    `PrintWindow` với `PW_RENDERFULLCONTENT`) — trả `image/jpeg`, chất lượng
    ~70 để giảm băng thông LAN.
  - `POST /input` `{ type: "mousedown|mousemove|mouseup|wheel|key", x, y,
    button, deltaY, keyCode }` → `PostMessage(hwnd, WM_...)` theo tọa độ đã
    scale (window plugin có thể lớn hơn vùng hiển thị → scale client rect).
  - `POST /close` → detach view, thoát tiến trình (exit 0).
  - `GET /ping` → alive check.
- Giữ nguyên SEH guard + registry chống mở 2 GUI (`_FX_GUI_PROCESSES` phía
  Python).
- Vị trí: `native_bridge/src/RenderFxJob.cpp` (hoặc file mới
  `FxGuiServer.cpp` cạnh nó — theo kích thước, tách nếu >300 dòng).

### 3.2. Python API (`app/api/v1/plugins.py` — mở rộng `open_fx_gui`)

- `POST /api/v1/plugins/fx-gui/open` `{ path, name }` → spawn bridge
  `--fx-gui`, đọc port, trả `{ success, embed_url: "http://127.0.0.1:<port>",
  already_running }`. Registry `_FX_GUI_PROCESSES` như hiện có.
- `POST /api/v1/plugins/fx-gui/close` `{ path }` → kill process (đã có luồng
  cleanup ở `_register_fx_gui_process`).
- Không cần proxy qua FastAPI: frontend gọi thẳng `embed_url` (CORS:
  `plugins.py` đã có middleware — kiểm tra thêm `Access-Control-Allow-Origin`
  cho port động).

### 3.3. UI — `app/static/js/app.jsx` (dùng chung cho 2 panel qua `vstRow`)

- `vstRow` thêm state per-slot: `guiOpen: { url } | null` (state nằm ở panel
  component, không phải trong `vstRow` — truyền qua props).
- Render slot: nút GUI hiện tại → **mở/đóng toggle**: nếu `guiOpen` null →
  gọi `openFxGuiEmbed` (API mới); nếu đang mở → hiển thị vùng embed.
- Vùng embed: `<div className="...">` chứa `<img src={url + '/frame'}>`
  refresh bằng `setInterval` ~100ms (10fps), overlay pointer handlers
  (`onMouseDown/Move/Up`, `onWheel`) → `fetch(url + '/input', POST)` với tọa độ
  relative tính theo bounding rect; keydown/keyup trên container.
  - Trong `MasteringModal`: vùng này **thay thế** vùng graph (khu vực
    canvas EQ/imager — xác định container chính xác lúc implement; ẩn bằng
    `hidden` class khi GUI mở, hiện lại khi close).
  - Trong `FXRackModal`: thay thế vùng scope/eq canvas.
- Click vào **tên VST đã load trong slot** (span tên hoặc chính slot) khi GUI
  đang đóng → mở lại embed (re-attach qua `/frame` poll, ping trước).
- Nút đóng GUI: nút X riêng trên vùng embed (hoặc nút GUI toggle) → gọi
  `/close`, dừng interval, trả graph về.
- Xóa slot (X) khi GUI đang mở → cũng phải đóng GUI (gọi `/close`).
- Nếu `/ping` fail (bridge chết ngoài ý muốn) → tự trả về graph + toast.

### 3.4. Không đổi

- Offline render (`--render-fx`), preset upload, Carla bridge, `--scan` — giữ
  nguyên. GUI nhúng chỉ là hiển thị/điều khiển, không đổi data model
  (`vstFxChain` giữ nguyên shape).

## 4. Phases

| Phase | Nội dung | Deliverable | Test |
|---|---|---|---|
| 0 | Bridge `--fx-gui`: HTTP server + BitBlt/PrintWindow capture + input relay | mở GUI Ozone trong browser tab thủ công qua URL | self-check: `/frame` trả JPEG kích thước khớp; `/input` click đúng vị trí |
| 1 | Python: `open` trả `embed_url`, registry, close, CORS | curl: open → frame 200 | unit: process spawn/cleanup |
| 2 | MasteringModal: embed + swap graph↔GUI + click mở lại | UI mastering hoàn chỉnh | E2E thủ công |
| 3 | FXRackModal: tương tự | UI fx rack hoàn chỉnh | E2E thủ công |
| 4 | Dọn: toast lỗi, cleanup interval, docs | commit | full test suite hiện có không vỡ |

Phase 0-1 có thể merge (cùng chạm bridge + plugins.py).

## 5. Rủi ro / giới hạn

- Plugin dùng layered window / DirectX surface → `PrintWindow` ra đen: fallback
  capture child control HWND hoặc dùng `BitBlt` từ `GetDC(NULL)` vùng rect —
  xử lý theo plugin cụ thể (Ozone chuẩn GDI, khả năng cao OK).
- Input tọa độ: scale theo client rect; plugin bắt absolute tọa độ cần
  `WM_MOUSEMOVE` trước click (gửi mousemove kèm).
- FPS ~10-15 đủ chỉnh thông số; không phải realtime video — ghi chú UI.
- Chỉ Windows desktop có VST GUI (Linux bridge SF2/SFZ — giữ nguyên).
- Keyboard input: chỉ forward khi panel đang focus, tránh nuốt phím toàn app.

## 6. License

- Không đổi: `native_bridge` MIT, không nhúng binary plugin, không quay lại
  pedalboard.

## 7. Ghi chú triển khai (Linux — đã làm)

- `native_bridge/src/FxGuiServer.cpp` (mới, ~316 dòng): HTTP server Winsock trên
  worker thread; `/frame` = `BitBlt` + fallback `PrintWindow PW_RENDERFULLCONTENT`
  khi ảnh toàn đen, JPEG quality 70 qua libjpeg-turbo (`jpeg_mem_dest`);
  `/input` relay `PostMessage` (mousedown/move/up, wheel deltaY*120, keydown/up,
  coords scale client rect); `/close` stop flag + `WM_CLOSE`; `GET /404`.
  `int fxGuiServerLoop(HWND)` chạy message pump STA, join HTTP thread.
- `RenderFxJob.cpp`: tách `fxGuiSetup()` dùng chung; `run_open_fx_gui` giữ hành
  vi cũ; thêm `run_fx_gui_server(jobPath)` (offscreen, userData=0);
  stub `#else !_WIN32` trả 1. `main.cpp`: dispatch `--fx-gui <job.json>`.
- `vcpkg.json` thêm `libjpeg-turbo`; `CMakeLists.txt` chỉ build FxGuiServer khi
  WIN32 + `find_package(JPEG REQUIRED)` + `JPEG::JPEG`.
- `app/api/v1/plugins.py`: `FxGuiRequest.embed`, model `FxGuiCloseRequest`,
  `open_fx_gui` spawn `--fx-gui` đọc `SF_FXGUI_PORT=` từ stdout → `embed_url`,
  trả `{success, started, already_running, embed_url, cmd}`; thêm
  `POST /api/v1/plugins/fx-gui/close` (terminate → wait 5s → kill → prune).
  CORS `allow_origins=["*"]` + bridge tự gửi ACAO `*`.
- `app/static/js/app.jsx`: component `VstGuiEmbed` (module scope, dùng chung 2
  panel) — img refresh 100ms, ping 2s, relay pointer/wheel/key với tọa độ scale,
  nút "✕ Đóng GUI" → `/close`. MasteringModal + FXRackModal: state
  `guiOpen {path,url}`, swap vùng graph↔GUI bằng ternary, cleanup unmount,
  bridge chết → toast + trả về graph.
- Tests: `tests/test_plugin_api.py` +4 (mở embed trả url, không port → 500,
  close kill, close unknown) — mock `find_bridge_exe` + `Popen`.
- Kết quả: `node build.mjs` BUILD OK; pytest 116 passed, 1 failed
  (`test_find_bridge_exe_dev` pre-existing — Linux thiếu binary bridge).
- Giới hạn: bridge C++ chưa build/test thật (Linux không có CMake/Win32) —
  Windows làm 0W1/0W2; E2E GUI nhúng thật chưa chạy — Windows làm 1W1-4W1.