SonicForgeStudio/TASKS_LINUX_WINDOWS.md

TASKS: Nhúng VST GUI — tách theo máy (Linux / Windows)

Nguồn: PLAN_MASTERBUS_VST_GUI_EMBED.md (Phase 0-4). Mỗi task ghi rõ máy thực hiện, file đụng, lệnh, deliverable, test, phụ thuộc.

Nguyên tắc tách:

• Linux (máy dev hiện tại): viết mọi source code (C++ bridge, Python API, frontend JSX), build frontend, chạy unit test (mock bridge), commit.
• Windows (máy chạy VST thật): build bridge C++ (MSVC/vcpkg), mọi E2E thật với plugin (Ozone...) — BitBlt/PrintWindow/SendMessage chỉ chạy Windows.
• Linux KHÔNG build được bridge (CMake bỏ VST3/GUI khi không WIN32; main_linux.cpp chỉ render offline). Linux KHÔNG có VST GUI để test E2E thật.

Ký hiệu: [L] = làm trên Linux · [W] = làm trên Windows.

---

PHASE 0 — Bridge --fx-gui (HTTP server + capture + input relay)

Task 0L1 — Viết FxGuiServer.cpp (hoặc mở rộng RenderFxJob.cpp nếu <300 dòng)

• Máy: [L] · File: native_bridge/src/FxGuiServer.cpp (mới) + native_bridge/src/RenderFxJob.cpp (hook mode --fx-gui)
• Nội dung (giữ nguyên phần attach IPlugView có sẵn fxGuiAttachSafe):
  • Mode --fx-gui <job.json>: sau khi attach view, khởi động HTTP server mini port ngẫu nhiên → in SF_FXGUI_PORT=<port> ra stdout (Python đọc).
  • GET /frame → chụp HWND plugin bằng BitBlt (fallback PrintWindow PW_RENDERFULLCONTENT) → trả image/jpeg quality ~70.
  • POST /input {type, x, y, button, deltaY, keyCode} → PostMessage/SendMessage theo tọa độ scale client rect (gửi WM_MOUSEMOVE trước click).
  • POST /close → detach view, thoát exit 0. GET /ping → alive.
• Toàn bộ Win32 API → bọc #ifdef _WIN32 hoặc chỉ build khi WIN32 (xem Task 0L2).
• Lệnh kiểm tra: không build được trên Linux — chỉ kiểm tra bằng mắt/syntax (g++ -fsyntax-only không đủ do thiếu windows.h → bỏ qua, sang Task 0W1).
• Deliverable: source bridge có mode --fx-gui.
• Phụ thuộc: không.

Task 0L2 — Cập nhật CMakeLists.txt cho source mới

• Máy: [L] · File: native_bridge/CMakeLists.txt
• Thêm source file mới vào target daw_vst_bridge CHỈ khi WIN32 (giữ Linux build không vỡ — Linux hiện build main_linux.cpp render-only).
• Lệnh kiểm tra: cmake -S native_bridge -B /tmp/nb-linux-check && cmake --build /tmp/nb-linux-check --target daw_vst_bridge → PASS trên Linux.
• Deliverable: Linux build vẫn xanh, Windows build có file mới.
• Phụ thuộc: 0L1.

Task 0W1 — Build bridge trên Windows

• Máy: [W] · Lệnh: powershell -ExecutionPolicy Bypass -File build/scripts/build_native_bridge.ps1 (bootstrap vcpkg, fluidsynth, sfizz 1.2.3, vst3sdk submodule, CMake VS2019 x64, copy daw_vst_bridge.exe + libfluidsynth-3.dll → src-tauri\binaries\).
• Điều kiện máy: VS Build Tools 2019+, CMake, git, đã pull submodule (git submodule update --init --recursive -- native_bridge/vst3sdk).
• Deliverable: native_bridge/build/Release/daw_vst_bridge.exe + sidecar trong src-tauri\binaries\.
• Test: exe tồn tại, chạy --help không crash.
• Phụ thuộc: 0L1, 0L2 (pull code mới về Windows trước).

Task 0W2 — Self-check bridge --fx-gui thủ công

• Máy: [W]
• Lệnh:
  1. Tạo job.json: {"path": "C:\\VST\\Ozone11.vst3", "name": "Ozone 11"}.
  2. native_bridge\build\Release\daw_vst_bridge.exe --fx-gui job.json → đọc port từ stdout.
  3. curl http://127.0.0.1:<port>/ping → alive.
  4. curl -o frame.jpg http://127.0.0.1:<port>/frame → JPEG, kích thước = kích thước GUI plugin.
  5. curl -X POST http://127.0.0.1:<port>/input -H "Content-Type: application/json" -d '{"type":"mousemove","x":100,"y":100,"button":0}' rồi {"type":"mousedown","x":100,"y":100,"button":0} + mouseup → click trúng nút trong GUI (quan sát đổi trạng thái).
  6. curl -X POST http://127.0.0.1:<port>/close → process thoát exit 0.
• Deliverable: /frame trả ảnh đúng, /input điều khiển được, /close sạch.
• Phụ thuộc: 0W1.

---

PHASE 1 — Python API (embed_url + registry + close + CORS)

Task 1L1 — Mở rộng open_fx_gui + thêm fx-gui/close

• Máy: [L] · File: app/api/v1/plugins.py
• Nội dung:
  • Spawn bridge với --fx-gui (thay/giữ --open-fx-gui), đọc port từ stdout (SF_FXGUI_PORT=) với timeout → trả { success, embed_url: "http://127.0.0.1:<port>", already_running }.
  • Giữ registry _FX_GUI_PROCESSES + _sf_plugin_path chống mở trùng.
  • Thêm POST /fx-gui/close {path} → tìm process theo _sf_plugin_path → terminate.
  • CORS: đảm bảo Access-Control-Allow-Origin cho origin app (port động) — kiểm tra middleware hiện có trong plugins.py, thêm nếu thiếu.
• Lệnh kiểm tra: python3 -m pytest tests/test_plugin_api.py -q → PASS (thêm unit test: mock subprocess.Popen → assert spawn args, embed_url parse, close kill, registry prune).
• Deliverable: API mới + unit test.
• Phụ thuộc: 0L1 (chỉ cần biết contract stdout port; có thể làm song song 0W).

Task 1W1 — Test API thật trên Windows

• Máy: [W] · Điều kiện: chạy app (backend FastAPI) + bridge đã build (0W1).
• Lệnh:
  1. curl -X POST http://127.0.0.1:<app>/api/v1/plugins/fx-gui/open -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"path":"C:\\VST\\Ozone11.vst3","name":"Ozone 11"}' → embed_url.
  2. curl http://<embed_url>/frame → 200 JPEG.
  3. curl -X POST .../fx-gui/close -d '{"path":"C:\\VST\\Ozone11.vst3"}' → process chết (Task Manager / Get-Process).
• Deliverable: API chạy thật, embed_url truy cập được, close sạch.
• Phụ thuộc: 1L1, 0W1.

---

PHASE 2 — MasteringModal: embed GUI trong panel

Task 2L1 — Code embed trong app/static/js/app.jsx (MasteringModal + vstRow)

• Máy: [L] · File: app/static/js/app.jsx
• Nội dung (state ở component panel, truyền qua props như đã làm với showCarla):
  • State per-slot guiOpen: { url } | null (MasteringModal).
  • Nút GUI → toggle: mở → gọi API fx-gui/open → lưu embed_url; đang mở → đóng.
  • Vùng embed: <img src={url + '/frame'}> refresh setInterval 100ms; overlay onMouseDown/Move/Up + onWheel → fetch(url + '/input', POST) tọa độ theo bounding rect; onKeyDown/Up trên container (chỉ khi panel focus).
  • Swap graph↔GUI: ẩn vùng canvas EQ/imager bằng hidden khi GUI mở, hiện khi đóng.
  • Click tên VST trong slot khi GUI đang đóng → mở lại embed (ping trước).
  • Nút X đóng GUI → POST /close, clearInterval, trả graph. Xóa slot khi GUI mở → cũng gọi /close.
  • /ping fail (bridge chết) → trả graph + toast.
• Lệnh kiểm tra:
  • node build.mjs (hoặc npm run build) → BUILD OK (syntax JSX).
  • Chạy backend Linux + mở app → verify UI không vỡ (GUI nhúng không test được thật vì thiếu bridge — dùng mock nếu cần: server node trả /frame JPEG fake + /input log).
• Deliverable: MasteringModal nhúng GUI + swap + đóng sạch.
• Phụ thuộc: 1L1 (contract API).

Task 2W1 — E2E thật MasteringModal

• Máy: [W] · Điều kiện: 2L1 + 0W1 + 1W1 pass.
• Test tay: mở app → Mastering Panel → thêm Ozone → GUI nhúng hiện TRONG panel (thay vùng graph) → click/scroll điều khiển plugin → đóng → graph trả về → click tên VST mở lại → Xóa slot khi GUI mở → GUI đóng + slot xóa, không crash.
• Deliverable: UI mastering hoàn chỉnh.
• Phụ thuộc: 2L1, 1W1.

---

PHASE 3 — FXRackModal: embed GUI trong panel

Task 3L1 — Code embed trong FXRackModal

• Máy: [L] · File: app/static/js/app.jsx (FXRackModal — vùng scope/eq canvas)
• Nội dung: tương tự 2L1 nhưng trong FXRackModal; lưu ý vùng thay thế là scopeCanvasRef/eqCurveRef (đã có fallback Carla ở đây — không đụng).
• Lệnh kiểm tra: node build.mjs → BUILD OK; backend Linux + mở app → UI không vỡ.
• Deliverable: FXRackModal nhúng GUI + swap + đóng sạch.
• Phụ thuộc: 2L1 (tái dùng pattern), 1L1.

Task 3W1 — E2E thật FXRackModal

• Máy: [W] · Điều kiện: 3L1.
• Test tay: FX Rack Panel → thêm VST FX → GUI nhúng trong panel → điều khiển → đóng → graph trả về. Track cũ có module Carla → vẫn hiện fallback "đã bị gỡ" + nút gỡ module (không vỡ).
• Deliverable: UI fx rack hoàn chỉnh.
• Phụ thuộc: 3L1.

---

PHASE 4 — Dọn + commit + regression

Task 4L1 — Dọn code, docs, commit

• Máy: [L]
• Nội dung:
  • Toast lỗi đầy đủ (mở GUI fail, bridge chết, close fail).
  • clearInterval khi unmount/close (tránh leak).
  • Cập nhật PLAN_MASTERBUS_VST_GUI_EMBED.md trạng thái HOÀN THÀNH + ghi chú giới hạn (FPS ~10-15, Windows-only).
  • git add -A && git commit (tin nhắn: embed native VST GUI in mastering + fx rack).
• Lệnh kiểm tra:
  • node build.mjs → BUILD OK.
  • python3 -m pytest tests/ -q → toàn bộ test hiện có PASS (1 fail pre-existing test_find_bridge_exe_dev do thiếu binary Linux — ghi chú, không phải regression).
• Deliverable: commit sạch, docs cập nhật.
• Phụ thuộc: 2L1, 3L1 (code ổn).

Task 4W1 — Regression full trên Windows

• Máy: [W] · Điều kiện: 4L1 (pull code mới).
• Test tay toàn bộ: Mastering + FX Rack GUI nhúng; render offline (--render-fx) không vỡ; Carla (MasteringModal) vẫn chạy; preset upload; scan plugin.
• Deliverable: bản Windows sẵn sàng dùng.
• Phụ thuộc: 4L1.

---

Thứ tự thực hiện tối ưu

Linux:  0L1 → 0L2 ──→ 1L1 ──→ 2L1 ──→ 3L1 ──→ 4L1 (commit)
Windows:          0W1 → 0W2 ──→ 1W1 ──→ 2W1 ──→ 3W1 ──→ 4W1
                     (pull code sau 0L2)   (pull sau 2L1) ...

Song song được: 1L1 (contract stdout) với 0W1/0W2; 2L1/3L1 với 0W/1W. Chặn: mọi task Windows cần pull code từ Linux trước.