SonicForgeStudio/WALKTHROUGH_WINDOWS.md

WALKTHROUGH WINDOWS — Nhúng native VST GUI (phần Windows)

Máy Windows thực hiện nốt phần còn lại theo TASKS_LINUX_WINDOWS.md (tasks 0W1, 0W2, 1W1, 2W1, 3W1, 4W1). Code Linux đã commit và push — pull code mới về trước:

git pull origin standalone-shm-bridge
git submodule update --init --recursive -- native_bridge/vst3sdk

Điều kiện máy: VS Build Tools 2019+, CMake, git, git-lfs (nếu vst3sdk dùng).

---

0W1 — Build bridge

powershell -ExecutionPolicy Bypass -File build/scripts/build_native_bridge.ps1

Lưu ý thay đổi mới trong phần này (so với lần build cũ):

• native_bridge/vcpkg.json thêm libjpeg-turbo — vcpkg manifest tự cài, không cần làm gì thêm, nhưng lần build đầu sẽ tải thêm package này.
• native_bridge/CMakeLists.txt: thêm src/FxGuiServer.cpp vào target daw_vst_bridge (chỉ khi WIN32) + find_package(JPEG REQUIRED) + link JPEG::JPEG. Nếu script build cũ không chạy cmake -S native_bridge mà dùng đường dẫn cố định, hãy đảm bảo nó re-configure (xóa native_bridge/build nếu cần).
• Script phải copy daw_vst_bridge.exe + DLL (fluidsynth, jpeg) sang src-tauri\binaries\ (chỉ các DLL cần thiết; libjpeg-turbo thường static theo manifest, nếu build động thì copy luôn jpeg62.dll).
• Trên máy thật: script hiện KHÔNG copy jpeg62.dll (build động) — copy tay: copy native_bridge\build\Release\jpeg62.dll src-tauri\binaries\.

PASS khi: native_bridge\build\Release\daw_vst_bridge.exe tồn tại và daw_vst_bridge.exe --help không crash.

---

0W2 — Self-check bridge --fx-gui (chưa cần app)

1. Tạo job.json cạnh exe:

   {"path": "C:\\VST\\Ozone11.vst3", "name": "Ozone 11"}
   

   (đổi path sang plugin VST3 bất kỳ đã cài trên máy Windows).
2. Chạy (giữ terminal mở):

   native_bridge\build\Release\daw_vst_bridge.exe --fx-gui job.json
   

   • stdout in dòng SF_FXGUI_PORT=<port> → ghi lại port.
   • Không có cửa sổ plugin hiện ra — window bị đặt off-screen (-20000,-20000) để capture; điều khiển qua HTTP, đây là thiết kế.
3. Kiểm tra từ terminal khác:

   curl http://127.0.0.1:<port>/ping
   curl -o frame.jpg http://127.0.0.1:<port>/frame
   curl -X POST http://127.0.0.1:<port>/input -H "Content-Type: application/json" -d '{"type":"mousemove","x":100,"y":100,"button":0}'
   curl -X POST http://127.0.0.1:<port>/input -H "Content-Type: application/json" -d '{"type":"mousedown","x":100,"y":100,"button":0}'
   curl -X POST http://127.0.0.1:<port>/input -H "Content-Type: application/json" -d '{"type":"mouseup","x":100,"y":100,"button":0}'
   curl -X POST http://127.0.0.1:<port>/input -H "Content-Type: application/json" -d '{"type":"wheel","x":100,"y":100,"deltaY":120}'
   curl -X POST http://127.0.0.1:<port>/close
   

   • /frame → JPEG (mở frame.jpg xem GUI plugin hiển thị đúng, không đen).
   • /input → click trúng nút trong GUI (plugin đổi trạng thái — để biết được, hãy mở song song GUI plugin bằng app cũ hoặc quan sát frame.jpg trước/sau click).
   • /close → tiến trình thoát exit 0.

PASS khi: frame không đen, input điều khiển được, close sạch.

Nếu /frame ra ảnh đen dù GUI thật hiển thị: bridge đã tự fallback PrintWindow PW_RENDERFULLCONTENT khi BitBlt đen; plugin layered/DirectX (hiếm) có thể cần xử lý thêm — ghi lại plugin nào bị để theo dõi.

---

1W1 — Test API thật (backend FastAPI chạy trên Windows)

Chạy app như bình thường (backend + frontend). Frontend gọi:

• POST /api/v1/plugins/fx-gui {path, name, embed: true} → trả {success, started, already_running, embed_url, cmd}.
• POST /api/v1/plugins/fx-gui/close {path} → trả {success, closed}.

Cách test nhanh bằng curl (cần token — lấy từ app sau khi login, hoặc dùng UI thay vì curl; endpoint yêu cầu Authorization: Bearer <token>):

curl -X POST http://127.0.0.1:8000/api/v1/plugins/fx-gui -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"path":"C:\\VST\\Ozone11.vst3","name":"Ozone 11","embed":true}'
curl http://<embed_url>/frame -o frame.jpg
curl -X POST http://127.0.0.1:8000/api/v1/plugins/fx-gui/close -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"path":"C:\\VST\\Ozone11.vst3"}'

• embed:true (mặc định false → cửa sổ rời kiểu cũ, giữ nguyên).
• Port backend có thể khác 8000 — xem log app.
• CORS đã mở * + bridge tự trả Access-Control-Allow-Origin: * → browser LAN gọi thẳng embed_url được.

PASS khi: open trả embed_url truy cập được /frame; close làm process chết (Get-Process daw_vst_bridge không còn).

---

2W1 — E2E MasteringModal

1. Mở app → Mastering Panel.
2. Thêm VST (Ozone) vào master chain → GUI TỰ MỞ (addMasterVst gọi openMasterVstGui). Bấm thêm nút GUI trên slot lúc này → backend trả already_running:true + toast "GUI của plugin này đang mở sẵn" — đúng thiết kế, không spawn 2 GUI.
3. Kỳ vọng: GUI plugin hiện TRONG panel (thay vùng graph EQ/imager), header hiện "VST GUI — nhúng (frame-capture · ~10fps)".
4. Click/scroll/kéo trong vùng GUI → plugin phản hồi (thay preset, xoay nút).
5. Bấm "✕ Đóng GUI" → về graph; chờ ~2-3s (bridge thoát hẳn) rồi bấm nút GUI lại → mở lại. Bấm ngay trong ~1s đầu có thể vẫn nhận already_running (process chưa thoát) — không phải lỗi.
6. Xóa slot khi GUI đang mở → GUI đóng + slot xóa, không crash.
7. Tắt bridge thủ công (Task Manager kill daw_vst_bridge) → sau ~2s panel toast "Bridge VST GUI đã mất kết nối" và tự trả về graph.

PASS khi: toàn bộ thao tác trên ổn định.

---

3W1 — E2E FXRackModal

1. Mở app → FX Rack Panel (track bất kỳ).
2. Thêm VST FX vào insert chain → bấm nút GUI → GUI nhúng trong panel (thay vùng WORKSPACE CONTROLS + WAVE OBSERVER).
3. Điều khiển → đóng → graph trả về.
4. Track cũ có module Carla → vẫn hiện fallback "Carla Bridge đã bị gỡ khỏi FX Rack" + nút gỡ module (không vỡ).

PASS khi: ổn định như 2W1.

---

4W1 — Regression full

Test tay toàn bộ:

• Mastering + FX Rack GUI nhúng (2W1/3W1).
• Render offline (--render-fx) không vỡ — export WAV có FX.
• Carla (MasteringModal) vẫn chạy.
• Preset upload, scan plugin vẫn OK.

PASS khi: không có regression so với trước embed.

---

Ghi chú chung

• Frame capture ~10fps (img refresh 100ms) — đủ chỉnh thông số, không phải realtime video.
• Feature chỉ chạy Windows desktop (có VST GUI); Linux giữ bridge SF2/SFZ.
• Nếu sửa gì trên Windows: sửa ngược lên Linux repo (app.jsx là source, app.precompiled.js là bản build — đừng sửa tay).
• Lỗi thường gặp:
  • --fx-gui không in port → check job.json path đúng VST3, bridge build có libjpeg-turbo (thiếu JPEG → lỗi link).
  • /frame đen → plugin layered window; ghi plugin + thử fallback đã có.
  • App không mở GUI → xem log backend: thiếu embed trong payload hoặc find_bridge_exe không thấy exe trong install/ (cần copy exe + DLL vào src-tauri\binaries\ và app dùng đúng thư mục đó).