revert: compression zstd khong co trong schema nsis cua Tauri version hien tai

1. LOAD CHAM: PyInstaller onefile 723MB giai nen toan bo vao %TEMP% moi lan chay -> chuyen ONEDIR (engine.spec COLLECT) + bundle qua Tauri resources (resource_dir/daw_engine/daw_engine.exe) thay externalBin — khoi dong tuc thi khong giai nen
2. WINDOW PICKER: Tauri v2 khong co window.__TAURI__.dialog — goi invoke('plugin:dialog|open', {options:{directory:true}}) qua __TAURI__.core.invoke
3. ICON exe: bundle.icon chuyen icon.ico -> favicon.ico + thay 3 PNG bang favicon render
- build_windows.ps1 buoc 4: copy onedir dist/daw_engine -> src-tauri/resources/daw_engine

.dockerignore

@@ -0,0 +1,44 @@
+# ── Docker build context — loại bỏ mã nguồn/bí mật không cần vào image ──
+.git
+.gitignore
+.github
+
+# Mã nguồn client (JSX) — image CHỈ chứa bản precompiled (minified)
+app/static/js/app.jsx
+app/static/js/app.jsx.new
+*.jsx
+
+# Bí mật
+.env
+.env.*
+!.env.example
+
+# Dependencies / build cache
+node_modules
+__pycache__
+*.pyc
+.cache
+.pytest_cache
+
+# Tài liệu / kế hoạch / backup nội bộ
+wiki.md
+PLAN.md
+PLAN*
+plans/
+md/
+*.patch
+*.recovered
+index.html.recovered
+celerybeat-schedule
+celerybeat.pid
+
+# Dữ liệu runtime (mount volume riêng — KHÔNG chép vào image)
+app/storage/uploads
+app/storage/processed
+app/storage/sonicforge.db
+celerybeat-schedule
+
+# Test
+tests/
+tools/
+samples/

.env.example

@@ -0,0 +1,25 @@
+# ── SonicForge Studio — môi trường (SAO CHÉP sang .env — KHÔNG commit .env) ──
+
+# Redis / Celery
+REDIS_URL=redis://redis:6379/0
+CELERY_BROKER_URL=redis://redis:6379/0
+CELERY_RESULT_BACKEND=redis://redis:6379/0
+
+# LLM (server-side proxy — client không thấy key)
+OPENAI_API_BASE=http://localhost:11434/v1
+OPENAI_API_KEY=ollama
+
+# Auth
+SECRET_KEY=thay-bang-chuoi-ngau-nhien-dai
+DEFAULT_ADMIN_PASSWORD=thay-mat-khau-admin
+
+# Storage (đường dẫn trong container)
+STORAGE_DIR=/app/app/storage
+
+# ── Plugin directories ──
+# Đường dẫn HOST tới thư mục chứa VST / SoundFont / Pianobook — dùng trong
+# docker-compose.yml để mount vào container (đổi theo máy chạy Docker).
+# Mặc định: /home/locpham/daw_assets/...
+VST_DIR=/home/locpham/daw_assets/vst3
+SOUNDFONT_DIR=/home/locpham/daw_assets/soundfonts
+PIANOBK_DIR=/home/locpham/daw_assets/pianobook

.gitignore

@@ -29,3 +29,7 @@ samples/
 *.log
 celerybeat-schedule
 node_modules
+src-tauri/target/
+src-tauri/binaries/
+src-tauri/resources/daw_engine/
+src-tauri/vc_redist.x64.exe

DESKTOP_INSTALL_PLAN.md

@@ -0,0 +1,87 @@
+# DESKTOP INSTALL PLAN — SonicForge Studio (bản cài trực tiếp trên OS)
+
+Mô hình: **server chạy nền trên máy người dùng (localhost), client mở bằng browser**.
+Không cần Electron — tận dụng stack hiện có (FastAPI + static JS precompiled).
+Soundfonts do **người dùng tự tải vào thư mục riêng** và **khai báo** cho ứng dụng.
+
+---
+
+## 1. KIẾN TRÚC
+
+```
+┌─────────────────────────── NGƯỜI DÙNG (1 máy) ───────────────────────────┐
+│  Browser ──http://127.0.0.1:8000──▶ FastAPI (uvicorn, chạy NỀN)          │
+│                                        │                                 │
+│  ~/SonicForgeStudio/                    ├─ data/    (DB, uploads, cache) │
+│   ├─ data/sonicforge.db                 ├─ soundfonts/ (user tự bỏ .sf2) │
+│   ├─ soundfonts/*.sf2/.sf3              └─ quét nền 30s (scanner có sẵn) │
+│   └─ config.json  ← khai báo folder soundfont                            │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+## 2. ĐÓNG GÓI CÀI ĐẶT (per-OS) — server nền + browser client
+
+### Thành phần đóng gói
+| Thành phần | Vai trò |
+|---|---|
+| Python backend (`app/`, `requirements.txt`) | Server — **PyInstaller `--onedir`** → binary (không cần Python trên máy user; bảo vệ source tốt hơn so với chạy .py) |
+| `app/static/` (precompiled.js + css + vendor) | Client — đóng vào package, server phục vụ |
+| VST3 plugins (`vst_plugins/`) | Copy theo platform (win .dll / mac .vst3 / linux .so) |
+| Service wrapper | Tự khởi động server nền + mở browser khi login |
+
+### Cài đặt + service nền theo OS
+| OS | Installer | Service nền | Auto-open browser |
+|---|---|---|---|
+| **Windows** | Inno Setup (`.exe`) | Windows Service qua `NSSM`/`WinSW` hoặc Task Scheduler (logon) | `start http://127.0.0.1:8000` |
+| **macOS** | `.dmg` + `.app` (PyInstaller) | `launchd` LaunchAgent (`~/Library/LaunchAgents`) | `open http://127.0.0.1:8000` |
+| **Linux** | `.deb` / `.AppImage` | systemd **user** service (`~/.config/systemd/user/`) | `xdg-open http://127.0.0.1:8000` |
+
+- Server bind **`127.0.0.1`** (không lộ mạng), port mặc định 8000 (config được).
+- App gồm 2 tiến trình nhỏ: `web` (uvicorn) + `worker` (celery) — hoặc gộp worker vào web ở chế độ desktop (đơn giản: `--pool=solo`, chạy celery trong tiến trình riêng nếu cần render nặng).
+
+## 3. THƯ MỤC DỮ LIỆU NGƯỜI DÙNG
+```
+~/SonicForgeStudio/
+├── data/            # DB, uploads, processed (thay app/storage khi chạy desktop)
+├── soundfonts/      # USER tự tải .sf2/.sf3 vào đây (mặc định được quét)
+└── config.json      # cấu hình: soundfont_dirs, port, autostart...
+```
+- `config.py`: thêm `DATA_DIR` (env `SFDATA_DIR`, mặc định `~/SonicForgeStudio/data`), `SOUNDFONT_DIRS`.
+
+## 4. SOUNDFONT DO NGƯỜI DÙNG QUẢN LÝ (tải + khai báo)
+**Cơ chế hiện có (tận dụng):** `app/core/soundfont_scanner.py` — `SoundFontAutoScanner` quét nền 30s
+`/opt/daw_engine/soundfonts` + `storage/soundfonts` → catalog → API list qua `app/api/v1/plugins.py`.
+
+**Việc cần làm (mở rộng):**
+1. **Scanner nhận folder người dùng:** constructor nhận thêm `user_dirs` (từ `SOUNDFONT_DIRS` env + `config.json`) — merge vào catalog (ưu tiên: user > system).
+2. **Khai báo folder — 2 cách:**
+   - **UI** (chính): Settings → "Soundfonts" → nút **Add folder…** (chọn thư mục chứa .sf2) → lưu vào `config.json` → gọi scanner rescan.
+   - **config.json** (thủ công): `{ "soundfont_dirs": ["D:/SF", "/Users/me/sf"] }`.
+3. **API:** thêm endpoint `POST /api/v1/plugins/soundfonts/dirs` (đăng ký folder) + `GET .../dirs` (liệt kê) — scanner reload.
+4. **UI danh sách:** hiển thị catalog (tên SF, kích thước, folder nguồn) — chọn = load vào FluidSynth (luồng có sẵn qua `SonicSF.selectInstrument`).
+5. **Số hóa:** không upload file — server đọc trực tiếp từ đường dẫn user khai báo (không nhân đôi dữ liệu).
+
+## 5. BUILD + PHÁT HÀNH
+```
+code → build.mjs (precompiled + ?v=) → PyInstaller (server binary) → đóng installer theo OS
+→ ký số (tùy chọn) → phát hành (GitHub Releases / trang riêng)
+```
+- **GitHub Actions matrix** (windows-latest / macos-latest / ubuntu-latest): test → build → installer artifact.
+- Installer gồm: binary server, static/, VST plugins nền tảng, script tạo service + mở browser, mặc định tạo `~/SonicForgeStudio/` lần chạy đầu.
+
+## 6. CẬP NHẬT
+- **Version check**: khi mở app, gọi endpoint version (file `version.json` đóng kèm + so sánh remote) → thông báo bản mới + link tải installer.
+- Cập nhật = chạy installer mới (ghi đè, GIỮ NGUYÊN `~/SonicForgeStudio/` — data + soundfonts không đụng).
+- `?v=` cache-bust JS mỗi bản (cơ chế đã có) — browser không dính cache cũ.
+
+## 7. CHECKLIST CODE CẦN LÀM
+- [ ] `config.py`: `DATA_DIR`, `SOUNDFONT_DIRS` (env + config.json)
+- [ ] `soundfont_scanner.py`: nhận `user_dirs`, merge catalog, ưu tiên user
+- [ ] API: `POST/GET .../soundfonts/dirs` (đăng ký/liệt kê folder) + rescan
+- [ ] UI Settings → Soundfonts (Add folder, Browse, list, load)
+- [ ] `soundfontStorage.js`: chuyển hướng sang catalog folder-scan (giữ upload path cho dự án cũ)
+- [ ] PyInstaller spec: bundle static/ + vendor (libfluidsynth wasm, vst), bind 127.0.0.1
+- [ ] Service wrappers: Windows (NSSM/WinSW), macOS (launchd), Linux (systemd user) + auto-open browser
+- [ ] Installer scripts: Inno Setup (.exe), dmg (macOS), deb/AppImage (Linux)
+- [ ] CI matrix build 3 OS + release artifacts
+- [ ] `version.json` + in-app update check

DISTRIBUTION_PLAN.md

@@ -0,0 +1,85 @@
+# DISTRIBUTION PLAN — SonicForge Studio (Alpha → Beta → Production)
+
+Mục tiêu: phân phối ứng dụng cho người dùng **không chia sẻ mã nguồn**, có pipeline
+cập nhật liên tục. Áp dụng cho backend Python/FastAPI + frontend JS (Babel precompiled).
+
+---
+
+## 1. TÁCH BÍ MẬT — FILE .env
+
+| Biến | Dùng cho | Bắt buộc |
+|---|---|---|
+| `REDIS_URL` | Redis/Celery broker | ✓ |
+| `CELERY_BROKER_URL` / `CELERY_RESULT_BACKEND` | Celery | ✓ |
+| `OPENAI_API_BASE` / `OPENAI_API_KEY` | LLM server-side (client KHÔNG thấy key — `aiGateway.js` chỉ gọi proxy server) | ✓ |
+| `SECRET_KEY` | Auth token (app/core/auth.py) | ✓ (mặc định trống → phải set) |
+| `DEFAULT_ADMIN_PASSWORD` | Admin mặc định | thay đổi ở production |
+
+- File `.env.example` đã tạo (commit được). `.env` thật KHÔNG commit (đã vào `.dockerignore`).
+- **Nguyên tắc:** client JS không bao giờ chứa secret — mọi API key nằm server (env) hoặc proxy.
+
+## 2. BUILD IMAGE — KHÔNG CHIA SẺ MÃ NGUỒN
+
+### 2.1 Chặn source khỏi image (`.dockerignore` — đã tạo)
+Loại khỏi build context: `.git`, `app/static/js/app.jsx` (source JSX), `wiki.md`, `plans/`, `*.patch`, `.env`, `tests/`, `node_modules`, backup...
+
+### 2.2 Frontend — chỉ ship bản precompiled
+- Build JS: `node build.mjs` (Babel → `app.precompiled.js` minified) — **CHỈ bản minified vào image**, source `.jsx` bị `.dockerignore` chặn.
+- Bump `?v=` (cache-bust) mỗi bản phát hành — user cập nhật không dính cache cũ.
+
+### 2.3 Backend Python — giới hạn đọc source
+- Python không biên dịch native mặc định → `.py` vẫn đọc được trong image. 3 lớp bảo vệ:
+  1. **Registry riêng tư** (GHCR / Docker Hub private / Harbor) — image KHÔNG public — người dùng chỉ nhận qua pull có auth.
+  2. **Secret chỉ qua env** — không hardcode gì trong image.
+  3. *(Tùy chọn, giai đoạn sau)* compile Python bằng **Nuitka** → `.so` cho `app/core`, `app/api` (giữ `main.py`/`config.py` đọc được — không chứa bí mật).
+
+### 2.4 Cách build + push
+```bash
+# 1. Precompile JS + bump ?v=
+node build.mjs                       # hoặc: NODE=... babel ... (xem wiki)
+# 2. Build image (tag theo version)
+docker build -t ghcr.io/<org>/sonicforge-studio:v1.0.0-alpha.1 .
+docker push ghcr.io/<org>/sonicforge-studio:v1.0.0-alpha.1
+# 3. Production chạy image đã push (KHÔNG mount source):
+docker compose -f docker-compose.prod.yml up -d
+```
+- Compose production (`docker-compose.prod.yml` — đã tạo): image từ registry, `env_file: .env`,
+  volumes bền (uploads/processed/db), asset dirs qua env (`VST3_DIR`, `SOUNDFONTS_DIR`, `PIANOBOOK_DIR`),
+  KHÔNG có `.:/app` (bỏ mount dev của compose cũ).
+
+## 3. KẾ HOẠCH PHÁT HÀNH
+
+### Giai đoạn 1 — ALPHA (nội bộ dev/QA)
+- Tag: `v0.x.x-alpha.N` — chạy `docker compose up --build` (dev mount OK).
+- Log verbose; chưa quan tâm bảo mật; test tính năng + thu hồi nhanh.
+- Mỗi thay đổi: bump `?v=` → build → tag → ghi wiki.md.
+
+### Giai đoạn 2 — BETA (nhóm người dùng mời)
+- Tag: `v0.x.x-beta.N` — image push **registry riêng tư**.
+- Người dùng: `docker compose -f docker-compose.prod.yml pull && up -d` (chỉ cần `.env` + image).
+- Thu log lỗi: thêm endpoint `/health` + (tùy chọn) Sentry/self-host error tracking.
+- **Feature flags** (biến env `FEATURE_*`) để tắt tính năng rủi ro từ xa.
+
+### Giai đoạn 3 — PRODUCTION
+- Tag: `vX.Y.Z` (semver) + `latest`.
+- **Trước khi release:** backup volumes (`docker run --rm -v sf_db:/data -v $PWD:/backup alpine tar czf /backup/db-<ver>.tgz /data`), migrate dữ liệu nếu schema đổi.
+- Triển khai: pull image mới → recreate (rolling — web trước, worker sau) → healthcheck.
+- `SECRET_KEY`, `DEFAULT_ADMIN_PASSWORD`, API keys: quản lý qua secret manager (Docker secrets / vault) — không ở compose file.
+
+## 4. PIPELINE CẬP NHẬT (lặp lại mỗi release)
+```
+code mới → build.mjs (precompiled + ?v=) → docker build (tag mới)
+→ push registry → [beta/prod] pull + recreate → backup trước nếu prod → kiểm tra /health
+```
+- Phiên bản: `git tag vX.Y.Z` — build tag tự động từ git (`git describe --tags`).
+- Rollback: giữ tag cũ — `docker compose -f docker-compose.prod.yml up -d` với `IMAGE=...:<tag cũ>`.
+
+## 5. VIỆC CẦN LÀM (checklist)
+- [x] `.env.example` — liệt kê đủ 7 biến
+- [x] `.dockerignore` — chặn source/secret/docs
+- [x] `docker-compose.prod.yml` — production (registry + env_file + volumes, bỏ mount source)
+- [ ] Kiểm tra endpoint `/health` (tạo nếu chưa có — healthcheck compose đang trỏ tới)
+- [ ] Chọn registry (GHCR/Docker Hub private/Harbor) + tạo token CI
+- [ ] Nuitka compile `app/core`+`app/api` (tùy chọn — nếu cần bảo vệ backend chặt hơn)
+- [ ] CI (GitHub Actions): test → build → push tag → deploy beta tự động
+- [ ] Backup script volumes trước mỗi production release

LICENSE

@@ -0,0 +1,40 @@
+MIT License
+
+Copyright (c) 2026 SonicForge Studio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+## Third-party components
+
+Code viết riêng của dự án (app/static/js/services/*, components/*, app.jsx)
+thuộc license MIT trên.
+
+Các thành phần bên thứ ba giữ license gốc:
+
+- **React / react-dom** — MIT
+- **Babel** (@babel/cli, core, preset-react) — MIT
+- **jsdom** — MIT
+- **Tailwind CSS** (app/static/css/tailwind.min.css) — MIT
+- **Lucide icons** — ISC
+- **FluidSynth 2.3.0** (app/static/js/vendor/libfluidsynth-2.3.0-sf3.js/.wasm) —
+  GNU LGPL v2.1+ — xem https://www.gnu.org/licenses/lgpl-2.1.html
+
+Chi tiết + attribution từng thành phần: xem THIRD_PARTY_LICENSES.md.

TEST_DEBUG_PLAN.md

@@ -0,0 +1,95 @@
+# TEST & DEBUG PLAN — SonicForge DAW Standalone (Windows .exe / .msi)
+
+Áp dụng cho bản đóng gói Tauri v2 + PyInstaller (xem `DESKTOP_INSTALL_PLAN.md`,
+`build_windows.ps1`, `engine.spec`, `src-tauri/`).
+
+---
+
+## 0. Cổng kiểm soát TRƯỚC khi build (pre-build gates — chạy trên máy dev)
+
+```powershell
+# 1. Backend tests (repo đã có 86 tests pytest)
+python -m pytest tests/ -x -q
+
+# 2. Frontend syntax + bundle
+node --check app/static/js/app.precompiled.js
+node build.mjs                      # rebuild app.precompiled.js từ app.jsx
+
+# 3. Python syntax của entry + spec
+python -m py_compile desktop_engine.py engine.spec app/config.py app/tasks/worker.py
+
+# 4. Chạy thử engine độc lập (chưa cần Tauri)
+python desktop_engine.py            # mở browser: http://127.0.0.1:8000/docs
+```
+
+Gate: tất cả PASS mới chạy `build_windows.ps1`.
+
+---
+
+## 1. TEST PLAN — theo 6 kịch bản của tài liệu gốc
+
+| # | Kịch bản | Cách kiểm thử | Kết quả mong đợi |
+|---|---|---|---|
+| 1 | **Lifecycle & Process Spawn** | Mở app → Task Manager tìm `daw_engine.exe` → đóng cửa sổ → kiểm tra lại | Engine xuất hiện lúc launch; BIẾN MẤT hoàn toàn khi đóng (không orphan). Engine còn có watchdog: nếu cha chết đột ngột, tự thoát ≤1s |
+| 2 | **Port 8000 & Fallback** | Mở app → browser truy cập `http://localhost:8000/docs`; hoặc chiếm sẵn port 8000 (vd `net stop` dịch vụ khác / chạy server khác) rồi mở app | Swagger UI hiển thị. Khi 8000 bị chiếm → engine tự chuyển 8001…8010, loader page trong app tự redirect tới port đúng |
+| 3 | **VST3 Local Scan (Windows)** | Plugin Manager → set path `C:\Program Files\Common Files\VST3` → **[Scan]** | Phát hiện đúng VST3 đã cài (Vital, Surge XT, FabFilter…). Scan state lưu ở `%APPDATA%\SonicForgeDAW\storage\sf_scan_state.json` |
+| 4 | **Isolation & Crash Protection** | Load 1 VST3 không ổn định / giả lập crash | UI hiện thông báo lỗi, cửa sổ DAW vẫn phản hồi (tiến trình engine riêng — shell không chết theo) |
+| 5 | **Storage Persistence (`%APPDATA%`)** | Mở Explorer tới `%APPDATA%\SonicForgeDAW\storage\` | Có `sonicforge.db`, `sf_scan_state.json`, `uploads/`, `processed/`, `soundfonts/` — **không** nằm trong thư mục cài đặt (onefile giải nén tạm sẽ bị xóa khi thoát) |
+| 6 | **Audio Export / Bouncing** | Click **Export WAV** ở chế độ Standalone | File `.wav` render đúng (VST3 + SoundFont qua Pedalboard/FluidSynth) |
+
+### 1.1 Kiểm thử cài đặt (installer)
+- **NSIS**: cài trên máy sạch (không có Python, không có VC++ redist) → app chạy được, `hooks.nsh` tự cài VC redist. Gỡ cài bằng Control Panel → không còn process, không còn shortcut.
+- **MSI**: cài qua `msiexec /i SonicForgeDAW_1.0.0_x64_en-US.msi` (hoặc double-click) → tương đương; kiểm tra repair/uninstall.
+- **Nâng cấp**: cài bản mới đè bản cũ → `%APPDATA%\SonicForgeDAW\storage` GIỮ NGUYÊN (dữ liệu người dùng không mất).
+- **SmartScreen/AV**: lần đầu chạy có thể bị chặn ("More info → Run anyway"); bản production phải ký số (signtool + certificate DigiCert/Sectigo).
+
+### 1.2 Kiểm thử hồi quy (regression — sau mỗi thay đổi code)
+- `pytest tests/` — 86 test hiện có (conftest fixture dùng test client).
+- Smoke UI thủ công: play/pause, piano roll, FX rack, save/load project, soundfont scan.
+
+---
+
+## 2. DEBUG WORKFLOWS
+
+### 2.1 Engine (Python sidecar) không start / crash âm thầm
+1. Mở log: `%APPDATA%\SonicForgeDAW\logs\engine.log` (desktop_engine.py ghi log ra file vì `console=False`).
+2. Chạy thủ công engine có console: sửa `console=True` trong `engine.spec` → rebuild → chạy `dist\daw_engine.exe` từ cmd → xem traceback trực tiếp.
+3. Test độc lập không cần Tauri: `python desktop_engine.py` (dev) — đúng code path, có stdout.
+
+### 2.2 UI (WebView2)
+- **F12 / Ctrl+Shift+I** trong cửa sổ app: mở DevTools (đã bật `"devtools": true` trong `tauri.conf.json`) — Console, Network, Web Audio context.
+- `devUrl: "http://localhost:8000"` — bản dev có thể chạy `tauri dev` với engine chạy tay.
+
+### 2.3 Sidecar không spawn / không thấy engine
+- Kiểm tra `src-tauri\binaries\daw_engine-x86_64-pc-windows-msvc.exe` có tồn tại (build script copy tự động).
+- Chạy `npx tauri build` lần đầu: nếu thiếu sidecar → lib.rs `expect("sidecar daw_engine not found")` fail rõ ràng.
+- Kiểm tra port bị chiếm: `netstat -ano | findstr :8000`.
+
+### 2.4 Windows build lỗi (máy dev)
+- Rust toolchain: `rustup default stable-msvc` (bắt buộc MSVC toolchain cho Tauri Windows).
+- WebView2 runtime: Win10/11 có sẵn; máy cũ cài [WebView2 Evergreen](https://developer.microsoft.com/microsoft-edge/webview2/).
+- Nếu `tauri build` lỗi NSIS/MSI riêng: build riêng từng target `npx tauri build --bundles nsis` / `--bundles msi`.
+
+---
+
+## 3. Known Gaps (đã xử lý / chấp nhận)
+
+| Vấn đề | Trạng thái |
+|---|---|
+| Celery cần Redis broker | **Đã xử lý**: `SF_DESKTOP=1` → `task_always_eager=True` (chạy đồng bộ trong tiến trình, `memory://` broker + `cache+memory://` backend). Chế độ docker/cloud không đổi |
+| Storage khi frozen (onefile giải nén tạm) | **Đã xử lý**: `config.py` freeze-aware → writable data về `%APPDATA%\SonicForgeDAW\storage`, assets read-only trong `_MEIPASS` |
+| Port 8000 bị chiếm | **Đã xử lý**: probe 8000–8010 + loader page redirect tự động |
+| `engine.spec` console=False → mù log | **Đã xử lý**: log ra file `%APPDATA%\SonicForgeDAW\logs\engine.log` |
+| Soundfont scanner path `/opt/daw_engine/soundfonts` (Linux-only) | **Chấp nhận**: cần xác minh scanner bỏ qua path không tồn tại trên Windows (test scenario #5) |
+| `child.kill()` = TerminateProcess (không graceful 100%) | **Giảm thiểu**: watchdog parent-PID trong `desktop_engine.py` → engine tự shutdown sạch khi cha chết |
+
+---
+
+## 4. Checklist phát hành (release)
+
+- [ ] Pre-build gates PASS (mục 0)
+- [ ] `build_windows.ps1` chạy sạch, đủ 6 bước
+- [ ] 6 kịch bản test (mục 1) PASS trên máy sạch
+- [ ] Installer NSIS + MSI cài/gỡ/nâng cấp đúng
+- [ ] Ký số (production) — SmartScreen hết cảnh báo
+- [ ] Commit artifacts: `engine.spec`, `desktop_engine.py`, `src-tauri/`, `build_windows.ps1`, `tools/gen_icons.py`

THIRD_PARTY_LICENSES.md

@@ -0,0 +1,37 @@
+# THIRD-PARTY LICENSES — SonicForgeStudio
+
+Kiểm tra ngày 2026-08-07. Danh sách thành phần bên thứ ba + license.
+
+## 1. Dependencies (npm — package.json)
+| Thành phần | License | Ghi chú |
+|---|---|---|
+| react / react-dom 19.x | MIT | OK |
+| @babel/cli, @babel/core, @babel/preset-react | MIT | Chỉ build-time |
+| jsdom | MIT | Chỉ build-time/test |
+
+## 2. Thư viện nhúng (app/static)
+| File | Nguồn | License | Trạng thái |
+|---|---|---|---|
+| `css/tailwind.min.css` | Tailwind CSS | MIT | OK — nên giữ attribution |
+| `js/services/spessasynth_processor.min.js` | SpessaSynth (KHÔNG còn dùng — không được include trong index.html — chỉ FluidSynth) | MIT | ✅ KHÔNG có code nào gọi (chỉ còn comment cũ app.jsx:14276 + file chết) — có thể xóa file |
+| `js/vendor/libfluidsynth-2.3.0-sf3.js` + `.wasm` | FluidSynth 2.3.0 (Emscripten) | **LGPL-2.1+** | ⚠️ Bắt buộc giữ license notice + attribution + (nếu phân phối bản build) cung cấp link/tài liệu LGPL |
+| `js/services/fluidsynthLoader.js`, `worklets/fluidsynth-bridge.js` | Bản tự viết (bọc FluidSynth) | Dự án | OK |
+| Lucide icons (inline `data-lucide`) | Lucide | ISC (MIT-compatible) | OK |
+
+## 3. Nội dung âm thanh (app/storage)
+| File | Nguồn | License | Trạng thái |
+|---|---|---|---|
+| `soundfonts/518e850f-...sf2` | "General MIDI SoundFont v3.0" — © 2006-2010 Rich "Weeds" Nagel — "Some rights reserved" | Không có text đầy đủ trong file (chỉ ICOP ngắn). Tuyên bố: "created from various **commercial**, custom, and freeware soundfonts and samples" | ⚠️ RỦI RO: (a) điều kiện "some rights reserved" không rõ ràng (thường là CC-BY — cần ghi attribution; có thể hạn chế thương mại); (b) samples gốc có nguồn commercial — quyền tái phân phối phụ thuộc tuyên bố tác giả. **Khuyến nghị: thay bằng SF2 license rõ (FluidR3_GM — MIT/GPL-2; GeneralUser GS — CC-BY-SA; Arachno — public domain) HOẶC giữ + ghi attribution đầy đủ.** |
+| `uploads/user_anonymous_*.mp3` | File người dùng upload | Thuộc người dùng | OK — không phải thành phần phân phối |
+| SGM-V2.01 (xuất hiện trong log `sfId: SGM-V2.01`) | SGM-V2.01 | Freeware — tác giả cho phép dùng nhưng **hạn chế redistribution** (cần permission) | ⚠️ Nếu vẫn dùng để phân phối bản build — cần permission từ tác giả; không nhúng vào sản phẩm |
+
+## 4. Assets
+- `templates/favicon.svg`, `images/SonicForgeUI.png` — nội bộ (tự tạo) — OK.
+- Code trong `app/static/js/services/*`, `app/static/js/components/*`, `app.jsx` — tự viết — thuộc dự án.
+
+## KẾT LUẬN
+- **Không phát hiện vi phạm bản quyền rõ ràng** (không có code GPL bị nhúng vào project MIT; LGPL của FluidSynth tương thích nếu giữ notice).
+- **3 điểm cần xử lý trước khi phân phối công khai:**
+  1. Bổ sung `LICENSE` text (MIT + LGPL-2.1) + attribution cho SpessaSynth (MIT notice) và Tailwind.
+  2. Ghi attribution SF2 Rich Nagel ("General MIDI SoundFont v3.0 — © 2006-2010 Rich 'Weeds' Nagel — Some rights reserved") hoặc thay soundfont khác license rõ.
+  3. Không nhúng SGM-V2.01 vào bản phân phối (hạn chế redistribution).

app/api/v1/plugins.py

@@ -16,7 +16,121 @@ 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"
+SYSTEM_SF_DIR = settings.SOUNDFONT_DIR
+SYSTEM_VST_DIR = settings.VST_DIR
+
+# User dirs (Windows/macOS — người dùng chọn qua folder picker trong
+# Plugins Manager). File global (không per-user): desktop app 1 user.
+PLUGIN_DIRS_FILE = os.path.join(settings.STORAGE_DIR, "plugin_dirs.json")
+
+def _load_plugin_dirs() -> dict:
+    if os.path.exists(PLUGIN_DIRS_FILE):
+        try:
+            with open(PLUGIN_DIRS_FILE, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except Exception:
+            pass
+    return {}
+
+def _save_plugin_dirs(dirs: dict):
+    os.makedirs(settings.STORAGE_DIR, exist_ok=True)
+    with open(PLUGIN_DIRS_FILE, "w", encoding="utf-8") as f:
+        json.dump(dirs, f, indent=2)
+
+def _effective_dirs() -> dict:
+    """Env/.env (Docker) là base; user dirs (file) override nếu khai báo.
+
+    plugin_dirs: list thư mục user thêm trong Plugins Manager (mỗi thư mục
+    có thể chứa cả VST lẫn SoundFont — scan tự phân loại). Nếu user chưa
+    khai báo → fallback env VST_DIR + SOUNDFONT_DIR.
+    """
+    user = _load_plugin_dirs()
+    plugin_dirs = [d for d in (user.get("plugin_dirs") or []) if d]
+    vst_dir = settings.VST_DIR
+    soundfont_dir = settings.SOUNDFONT_DIR
+    # Backward compat: file cũ lưu vst_dir/soundfont_dir riêng → gộp vào list.
+    if not plugin_dirs:
+        if user.get("vst_dir"):
+            plugin_dirs.append(user["vst_dir"])
+        if user.get("soundfont_dir"):
+            plugin_dirs.append(user["soundfont_dir"])
+    if not plugin_dirs:
+        plugin_dirs = [vst_dir, soundfont_dir]
+    return {
+        "plugin_dirs": plugin_dirs,
+        "vst_dir": vst_dir,
+        "soundfont_dir": soundfont_dir,
+        "plugin_dirs_user_set": bool(user.get("plugin_dirs")),
+    }
+
+class DirsRequest(BaseModel):
+    vst_dir: Optional[str] = None
+    soundfont_dir: Optional[str] = None
+    plugin_dirs: Optional[list] = None
+
+@router.get("/dirs")
+async def get_plugin_dirs():
+    return {"success": True, **(_effective_dirs())}
+
+@router.post("/dirs")
+async def save_plugin_dirs(req: DirsRequest, current_user: dict = Depends(get_current_user)):
+    enforce_password_changed(current_user)
+    user = _load_plugin_dirs()
+    if req.plugin_dirs is not None:
+        user["plugin_dirs"] = [d.strip() for d in req.plugin_dirs if d and d.strip()]
+        # Xóa field cũ (đã gộp vào plugin_dirs) tránh nhầm lẫn
+        user.pop("vst_dir", None)
+        user.pop("soundfont_dir", None)
+    else:
+        if req.vst_dir is not None:
+            user["vst_dir"] = req.vst_dir.strip()
+        if req.soundfont_dir is not None:
+            user["soundfont_dir"] = req.soundfont_dir.strip()
+    _save_plugin_dirs(user)
+    return {"success": True, **(_effective_dirs())}
+
+@router.post("/scan")
+async def scan_plugin_dirs(background_tasks: BackgroundTasks = None,
+                           current_user: dict = Depends(get_current_user)):
+    """Scan các dir hiệu lực (env + user override): cập nhật catalog
+    soundfont (inspector/scanner) + liệt kê VST. Trả về danh sách riêng rẽ
+    VST (vst_found) + SoundFont (soundfonts) theo từng thư mục user khai báo."""
+    enforce_password_changed(current_user)
+    dirs = _effective_dirs()
+    plugin_dirs = dirs["plugin_dirs"]
+    # SoundFont: quét + inspect vào catalog (scan_once dùng dir hiệu lực)
+    scanner = SoundFontAutoScanner(system_sf_dirs=plugin_dirs, upload_sf_dir=UPLOAD_SF_DIR)
+    if background_tasks:
+        background_tasks.add_task(scanner.scan_once)
+    else:
+        scanner.scan_once()
+    catalog = scanner.get_catalog()
+    # VST + SoundFont: walk từng thư mục, phân loại riêng rẽ theo extension
+    vst_found = []
+    sf_found = []
+    for d in plugin_dirs:
+        if not os.path.isdir(d):
+            continue
+        for root, _dirs, files in os.walk(d):
+            for f in files:
+                low = f.lower()
+                if low.endswith(".vst3") or low.endswith(".dll") or low.endswith(".so"):
+                    vst_found.append({"name": os.path.splitext(f)[0],
+                                      "path": os.path.join(root, f),
+                                      "dir": d,
+                                      "type": "VST3" if low.endswith(".vst3") else "VST2"})
+                elif low.endswith(".sf2") or low.endswith(".sf3"):
+                    sf_found.append({"name": os.path.splitext(f)[0],
+                                     "path": os.path.join(root, f),
+                                     "dir": d})
+    return {
+        "success": True,
+        "plugin_dirs": plugin_dirs,
+        "vst_found": vst_found,
+        "vst_count": len(vst_found),
+        "soundfonts": sf_found,
+        "soundfont_count": len(sf_found),
+    }
 
 _inspector = None
 _scanner = None
@@ -24,20 +138,24 @@ _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)
+        d = _effective_dirs()
+        _inspector = SoundFontInspector(d["plugin_dirs"][0] if d["plugin_dirs"] else settings.SOUNDFONT_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)
+        d = _effective_dirs()
+        _scanner = SoundFontAutoScanner(system_sf_dirs=d["plugin_dirs"], 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)):
-    pm = PluginManager(upload_sf_dir=UPLOAD_SF_DIR)
+    d = _effective_dirs()
+    pm = PluginManager(vst_dir=d["vst_dir"], sf_dir=d["soundfont_dir"], upload_sf_dir=UPLOAD_SF_DIR)
     return pm.list_available()
 
 

app/config.py

@@ -1,16 +1,37 @@
 import os
+import sys
+
+
+def _app_dir():
+    if getattr(sys, "frozen", False):
+        # PyInstaller onefile: assets read-only nằm trong thư mục giải nén tạm
+        return os.path.join(sys._MEIPASS, "app")
+    return os.path.dirname(os.path.abspath(__file__))
+
+
+def _storage_dir():
+    if getattr(sys, "frozen", False):
+        # Dữ liệu ghi được (DB, uploads, processed) phải ngoài thư mục tạm
+        root = os.environ.get("APPDATA") or os.path.expanduser("~")
+        return os.path.join(root, "SonicForgeDAW", "storage")
+    return os.path.join(_app_dir(), "storage")
+
 
 class Settings:
     REDIS_URL: str = os.getenv("REDIS_URL", "redis://localhost:6379/0")
     CELERY_BROKER_URL: str = os.getenv("CELERY_BROKER_URL", "redis://localhost:6379/0")
     CELERY_RESULT_BACKEND: str = os.getenv("CELERY_RESULT_BACKEND", "redis://localhost:6379/0")
     
-    # __file__ is app/config.py, so dirname(__file__) = app/, dirname(app/) = project root
+    APP_DIR: str = _app_dir()
-    APP_DIR: str = os.path.dirname(os.path.abspath(__file__))
     BASE_DIR: str = os.path.dirname(APP_DIR)
     TEMPLATES_DIR: str = os.path.join(APP_DIR, "templates")
-    STORAGE_DIR: str = os.path.join(APP_DIR, "storage")
+    STORAGE_DIR: str = _storage_dir()
     UPLOADS_DIR: str = os.path.join(STORAGE_DIR, "uploads")
     PROCESSED_DIR: str = os.path.join(STORAGE_DIR, "processed")
 
+    # Plugin dirs — người dùng khai báo qua .env / docker-compose (Docker)
+    # hoặc qua Plugins Manager (Windows/macOS, lưu theo user).
+    VST_DIR: str = os.getenv("VST_DIR", "/opt/daw_engine/vst3")
+    SOUNDFONT_DIR: str = os.getenv("SOUNDFONT_DIR", "/opt/daw_engine/soundfonts")
+
 settings = Settings()

app/core/soundfont_scanner.py

@@ -8,7 +8,7 @@ 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"
+SYSTEM_SF_DIR = settings.SOUNDFONT_DIR
 UPLOAD_SF_DIR = os.path.join(settings.STORAGE_DIR, "soundfonts")
 
 
@@ -19,8 +19,11 @@ def _file_sig(path: str) -> tuple:
 
 
 class SoundFontAutoScanner:
-    def __init__(self, system_sf_dir=SYSTEM_SF_DIR, upload_sf_dir=UPLOAD_SF_DIR):
+    def __init__(self, system_sf_dir=SYSTEM_SF_DIR, upload_sf_dir=UPLOAD_SF_DIR,
-        self.system_sf_dir = system_sf_dir
+                 system_sf_dirs=None):
+        # system_sf_dirs (list) — nhiều thư mục user khai báo trong Plugins
+        # Manager. Fallback system_sf_dir (env/.env) nếu list rỗng.
+        self.system_sf_dirs = [d for d in (system_sf_dirs or []) if d] or [system_sf_dir]
         self.upload_sf_dir = upload_sf_dir
         self._catalog = {}
         self._lock = threading.Lock()
@@ -50,6 +53,15 @@ class SoundFontAutoScanner:
                 out.append((fname, os.path.join(directory, fname)))
         return out
 
+    def _all_sf_files(self) -> list:
+        """Gộp file .sf2/.sf3 từ TẤT CẢ thư mục hiệu lực (user dirs + upload)."""
+        out = []
+        for d in self.system_sf_dirs:
+            out.extend(self._sf_files(d))
+        if self.upload_sf_dir and os.path.isdir(self.upload_sf_dir):
+            out.extend(self._sf_files(self.upload_sf_dir))
+        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 {}
@@ -68,9 +80,9 @@ class SoundFontAutoScanner:
 
     def scan_once(self) -> bool:
         from app.core.soundfont_inspector import SoundFontInspector
-        inspector = SoundFontInspector(self.system_sf_dir, self.upload_sf_dir)
+        inspector = SoundFontInspector(self.system_sf_dirs[0], self.upload_sf_dir)
         found_new = False
-        dirs = [(self.system_sf_dir, "system")]
+        dirs = [(d, "system") for d in self.system_sf_dirs]
         if self.upload_sf_dir and os.path.isdir(self.upload_sf_dir):
             dirs.append((self.upload_sf_dir, "upload"))
 

app/core/vst_engine.py

@@ -99,8 +99,13 @@ _PLUGIN_MANAGER_INSTANCE = None
 _PLUGIN_MANAGER_ARGS = None
 _SF_INSTRUMENTS_CACHE = {}  # sf_id → list[presets]
 
-def get_plugin_manager(vst_dir="/opt/daw_engine/vst3", sf_dir="/opt/daw_engine/soundfonts", upload_sf_dir=None) -> "PluginManager":
+def get_plugin_manager(vst_dir=None, sf_dir=None, upload_sf_dir=None) -> "PluginManager":
-    """Singleton: reuse PluginManager when args match, else create new."""
+    """Singleton: reuse PluginManager when args match, else create new.
+    Default dirs từ settings (env/.env/docker-compose hoặc user override)."""
+    from app.config import settings as _st
+    vst_dir = vst_dir or _st.VST_DIR
+    sf_dir = sf_dir or _st.SOUNDFONT_DIR
+    upload_sf_dir = upload_sf_dir or _st.STORAGE_DIR + "/soundfonts"
     global _PLUGIN_MANAGER_INSTANCE, _PLUGIN_MANAGER_ARGS
     args = (vst_dir, sf_dir, upload_sf_dir)
     if _PLUGIN_MANAGER_INSTANCE is not None and _PLUGIN_MANAGER_ARGS == args:
@@ -155,9 +160,10 @@ def release_soundfont(path: str):
         _FLUID_CACHE[path] = (fl, ref - 1)
 
 class PluginManager:
-    def __init__(self, vst_dir="/opt/daw_engine/vst3", sf_dir="/opt/daw_engine/soundfonts", upload_sf_dir=None):
+    def __init__(self, vst_dir=None, sf_dir=None, upload_sf_dir=None):
-        self.vst_dir = vst_dir
+        from app.config import settings as _st
-        self.sf_dir = sf_dir
+        self.vst_dir = vst_dir or _st.VST_DIR
+        self.sf_dir = sf_dir or _st.SOUNDFONT_DIR
         self.upload_sf_dir = upload_sf_dir
         self._sf_scan_cache = None  # cache for _scan_soundfonts()
 

app/main.py

@@ -58,7 +58,27 @@ app.add_middleware(
 # Mount storage directory (must come before general /static mount)
 app.mount("/static/audio", StaticFiles(directory=settings.STORAGE_DIR), name="audio")
 # Mount app static files (js, css)
-STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
+# Dùng settings.APP_DIR (freeze-aware) thay vì os.path.dirname(__file__):
+# khi PyInstaller onefile, __file__ trỏ vào thư mục giải nén tạm _MEI...
+# nhưng static/templates nằm trong sys._MEIPASS/app (config.py đã xử lý).
+STATIC_DIR = os.path.join(settings.APP_DIR, "static")
+# ⚠️ Fallback an toàn: nếu vì lý do nào đó static không nằm đúng chỗ (vd
+# bundle thiếu file, chạy từ nơi khác), thử các vị trí khác; nếu vẫn không
+# có → TỰ TẠO thư mục rỗng để app KHÔNG crash khi khởi động (lỗi "Directory
+# does not exist" từ StaticFiles làm engine chết ngay lúc import — đã gặp).
+if not os.path.isdir(STATIC_DIR):
+    for cand in [
+        os.path.join(getattr(sys, "_MEIPASS", ""), "app", "static"),
+        os.path.join(os.path.dirname(os.path.abspath(__file__)), "static"),
+    ]:
+        if cand and os.path.isdir(cand):
+            STATIC_DIR = cand
+            break
+    else:
+        try:
+            os.makedirs(STATIC_DIR, exist_ok=True)
+        except OSError:
+            pass
 app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
 
 # Include routers
@@ -75,6 +95,10 @@ app.include_router(plugins_router, prefix="/api/v1/plugins", tags=["plugins"])
 app.include_router(media_router, prefix="/api/v1/media", tags=["media"])
 
 
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
+
 @app.get("/", response_class=HTMLResponse)
 async def get_index():
     index_path = os.path.join(settings.TEMPLATES_DIR, "index.html")

app/static/js/app.jsx

@@ -5284,14 +5284,71 @@ const PluginManagerModal = ({ isOpen, onClose, pluginsData }) => {
   const [localData, setLocalData] = React.useState(pluginsData);
   const [sfUploadStatus, setSfUploadStatus] = React.useState('');
   const [sfToDelete, setSfToDelete] = React.useState(null);
+  const [pmDirs, setPmDirs] = React.useState([]);
+  const [pmScanning, setPmScanning] = React.useState(false);
+  const [pmScanResult, setPmScanResult] = React.useState('');
+  const [pmScanData, setPmScanData] = React.useState(null); // { vst_found, soundfonts }
   React.useEffect(() => {
     if (isOpen) {
       window.SonicAPI.listPlugins()
         .then(data => setLocalData(data))
         .catch(() => setLocalData({ vst_instruments: [], soundfonts: [] }));
+      window.SonicAPI.getPluginDirs()
+        .then(d => setPmDirs(d.plugin_dirs || []))
+        .catch(() => {});
       setTimeout(() => { try { window.lucide.createIcons(); } catch(e) {} }, 50);
     }
   }, [isOpen]);
+  // Folder picker: Tauri v2 dialog qua invoke (window.__TAURI__.dialog KHONG
+  // ton tai trong v2 — plugin dialog chi co JS binding qua npm; goi truc tiep
+  // command 'plugin:dialog|open'). Fallback: prompt nhap path (browser).
+  const pickPluginFolder = async () => {
+    try {
+      if (window.__TAURI__ && window.__TAURI__.core && window.__TAURI__.core.invoke) {
+        const sel = await window.__TAURI__.core.invoke('plugin:dialog|open', {
+          options: { directory: true, multiple: false }
+        });
+        if (typeof sel === 'string' && sel) {
+          if (!pmDirs.includes(sel)) setPmDirs(prev => [...prev, sel]);
+        }
+        return;
+      }
+      const manual = window.prompt('Nhập đường dẫn thư mục plugin (VST / SoundFont):');
+      if (manual && manual.trim()) {
+        const p = manual.trim();
+        if (!pmDirs.includes(p)) setPmDirs(prev => [...prev, p]);
+      }
+    } catch (e) {
+      showToast('Browse failed: ' + (e.message || e), 'error');
+    }
+  };
+  const removePluginDir = (dir) => {
+    setPmDirs(prev => prev.filter(d => d !== dir));
+  };
+  // Lưu dirs (user override) + scan cả 2 thư mục → refresh list + catalog.
+  const saveAndScanDirs = async () => {
+    setPmScanning(true);
+    setPmScanResult('');
+    setPmScanData(null);
+    try {
+      await window.SonicAPI.savePluginDirs({ plugin_dirs: pmDirs });
+      const scan = await window.SonicAPI.scanPluginDirs();
+      setPmScanData({ vst_found: scan.vst_found || [], soundfonts: scan.soundfonts || [] });
+      const data = await window.SonicAPI.listPlugins();
+      setLocalData(data);
+      try {
+        const cat = await window.SonicAPI.getSoundfontCatalog();
+        window.__soundfontCatalog = cat;
+      } catch (_) {}
+      setPmScanResult(`VST: ${scan.vst_count || 0} | SoundFonts: ${scan.soundfont_count || 0}`);
+      showToast(`Scan xong: ${scan.vst_count || 0} VST, ${scan.soundfont_count || 0} SoundFonts.`, 'success');
+    } catch (err) {
+      setPmScanResult('Scan failed: ' + (err.message || err));
+      showToast('Scan failed: ' + (err.message || err), 'error');
+    } finally {
+      setPmScanning(false);
+    }
+  };
   const handleUploadSF = async (e) => {
     const file = e.target.files?.[0];
     if (!file) return;
@@ -5403,6 +5460,79 @@ const PluginManagerModal = ({ isOpen, onClose, pluginsData }) => {
               )
             ))
           ),
+          // Plugin directories section (folder picker + save + scan)
+          React.createElement('div', {
+            className: 'pt-4 mt-4 border-t border-[#383838]'
+          },
+            React.createElement('div', { className: 'flex items-center justify-between mb-2' },
+              React.createElement('h4', { className: 'text-xs font-bold text-zinc-400 uppercase' },
+                'Plugin Directories'),
+              React.createElement('button', {
+                className: 'px-3 py-1.5 bg-violet-800 hover:bg-violet-700 text-white text-xs font-semibold rounded transition flex items-center gap-1 shrink-0',
+                title: 'Add plugin directory (VST / SoundFont)',
+                onClick: pickPluginFolder
+              },
+                React.createElement('i', { 'data-lucide': 'plus', className: 'w-3 h-3' }), 'Add Directory')
+            ),
+            pmDirs.length === 0 &&
+              React.createElement('p', { className: 'text-[10px] text-zinc-600 mb-2 italic' },
+                'Chưa có thư mục nào. Nhấn Add Directory để chọn thư mục chứa VST / SoundFont.'),
+            pmDirs.map((dir, idx) =>
+              React.createElement('div', {
+                key: 'pdir_' + idx,
+                className: 'flex items-center gap-2 mb-1.5 bg-zinc-800/70 border border-zinc-700 rounded px-2 py-1.5'
+              },
+                React.createElement('button', {
+                  className: 'text-zinc-500 hover:text-red-400 transition shrink-0',
+                  title: 'Remove directory',
+                  onClick: () => removePluginDir(dir)
+                },
+                  React.createElement('i', { 'data-lucide': 'x', className: 'w-3.5 h-3.5' })),
+                React.createElement('span', {
+                  className: 'flex-1 text-[11px] text-zinc-300 font-mono truncate',
+                  title: dir
+                }, dir),
+                React.createElement('i', {
+                  'data-lucide': 'folder',
+                  className: 'w-3 h-3 text-zinc-600 shrink-0'
+                })
+              )
+            ),
+            React.createElement('div', { className: 'flex gap-2 items-center mt-2' },
+              React.createElement('button', {
+                className: 'px-4 py-2 bg-emerald-800 hover:bg-emerald-700 text-white text-xs font-semibold rounded transition flex items-center gap-1',
+                onClick: saveAndScanDirs
+              },
+                React.createElement('i', { 'data-lucide': 'search', className: 'w-3 h-3' }), 'Scan'),
+              pmScanning && React.createElement('span', { className: 'text-[10px] text-emerald-400' }, 'Scanning...'),
+              pmScanResult && React.createElement('span', { className: 'text-[10px] text-zinc-400' }, pmScanResult)
+            ),
+            pmScanData && React.createElement('div', { className: 'mt-3 space-y-2 max-h-40 overflow-y-auto' },
+              React.createElement('div', { className: 'text-[10px] font-bold text-violet-300 uppercase flex items-center gap-1' },
+                React.createElement('i', { 'data-lucide': 'cpu', className: 'w-3 h-3' }),
+                'VST Instruments (' + pmScanData.vst_found.length + ')'),
+              pmScanData.vst_found.length === 0 ?
+                React.createElement('p', { className: 'text-[10px] text-zinc-600 italic' }, 'Không tìm thấy VST.') :
+                pmScanData.vst_found.map((v, i) =>
+                  React.createElement('div', { key: 'sv_' + i, className: 'flex items-center gap-2 text-[11px] text-zinc-300' },
+                    React.createElement('span', { className: 'w-16 shrink-0 text-zinc-500 font-mono text-[9px] truncate' }, v.type || 'VST'),
+                    React.createElement('span', { className: 'truncate' }, v.name),
+                    React.createElement('span', { className: 'text-[9px] text-zinc-600 font-mono truncate ml-auto' }, v.dir)
+                  )
+                ),
+              React.createElement('div', { className: 'text-[10px] font-bold text-amber-300 uppercase flex items-center gap-1 mt-2' },
+                React.createElement('i', { 'data-lucide': 'music', className: 'w-3 h-3' }),
+                'SoundFonts (' + pmScanData.soundfonts.length + ')'),
+              pmScanData.soundfonts.length === 0 ?
+                React.createElement('p', { className: 'text-[10px] text-zinc-600 italic' }, 'Không tìm thấy SoundFont.') :
+                pmScanData.soundfonts.map((s, i) =>
+                  React.createElement('div', { key: 'ss_' + i, className: 'flex items-center gap-2 text-[11px] text-zinc-300' },
+                    React.createElement('span', { className: 'truncate' }, s.name),
+                    React.createElement('span', { className: 'text-[9px] text-zinc-600 font-mono truncate ml-auto' }, s.dir)
+                  )
+                )
+            )
+          ),
           // Upload section (bottom of right panel)
           React.createElement('div', {
             className: 'pt-4 mt-4 border-t border-[#383838]'
@@ -6469,6 +6599,155 @@ const SystemManagerModal = ({
   }, "Xóa")))))))));
 };
 
+/* ═══════════════════════════════════════════════════════════════════
+   ABOUT / HELP / PREFERENCES MODALS (menu Help + Tools → Preferences)
+   ═══════════════════════════════════════════════════════════════════ */
+const APP_VERSION = '1.0.0'; // khớp src-tauri/tauri.conf.json
+
+const AboutModal = ({ isOpen, onClose }) => {
+  if (!isOpen) return null;
+  return (
+    <div className="fixed inset-0 z-[9999] flex items-center justify-center bg-black/70 backdrop-blur-sm" onClick={onClose}>
+      <div className="bg-[#1e1e24] border border-zinc-700 rounded-xl shadow-2xl w-full max-w-md p-6 text-slate-200" onClick={e => e.stopPropagation()}>
+        <div className="flex items-center gap-3 mb-4">
+          <img src="/favicon.svg" alt="SonicForge Studio" className="w-12 h-12 rounded-lg bg-zinc-900 border border-zinc-700 shadow-lg object-contain p-0.5" />
+          <div>
+            <h2 className="text-lg font-bold text-white">SonicForge Studio</h2>
+            <p className="text-xs text-zinc-400">Professional DAW — v{APP_VERSION}</p>
+          </div>
+        </div>
+        <div className="space-y-2 text-sm">
+          <p className="text-zinc-300 leading-relaxed">Phần mềm sản xuất âm nhạc (DAW) — soạn nhạc, ghi âm, chỉnh sửa MIDI/Audio, SoundFont &amp; VST, trộn và master.</p>
+          <div className="pt-2 border-t border-zinc-800 space-y-1 text-xs">
+            <div className="flex items-center gap-2"><span className="text-zinc-500 w-20 shrink-0">Developer</span><span className="text-cyan-400 font-semibold">Lộc Phạm</span></div>
+            <div className="flex items-center gap-2"><span className="text-zinc-500 w-20 shrink-0">Email</span><a href="mailto:tranloclqd@gmail.com" className="text-cyan-400 hover:underline">tranloclqd@gmail.com</a></div>
+            <div className="flex items-center gap-2"><span className="text-zinc-500 w-20 shrink-0">Version</span><span className="text-zinc-300">{APP_VERSION}</span></div>
+            <div className="flex items-center gap-2"><span className="text-zinc-500 w-20 shrink-0">Build</span><span className="text-zinc-300">Standalone (Tauri v2 + PyInstaller)</span></div>
+          </div>
+        </div>
+        <div className="mt-5 flex justify-end">
+          <button onClick={onClose} className="px-4 py-1.5 bg-cyan-700 hover:bg-cyan-600 rounded text-xs font-bold text-white transition">Đóng</button>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+const HelpModal = ({ isOpen, onClose, lang }) => {
+  if (!isOpen) return null;
+  const vi = lang !== 'en';
+  const sections = vi ? [
+    { title: '🚀 Bắt đầu nhanh', body: 'Nhấn phím Cách (Space) để Play/Pause. Nhấn phím / để dừng. Dùng nút Record (●) để ghi âm/MIDI. Tạo track mới từ menu Track hoặc nút "+ Add Track".' },
+    { title: '🎹 MIDI & ARM', body: 'Bật nút ARM đỏ trên track để nhận phím từ MIDI keyboard. Vào menu Tools → MIDI Devices để chọn thiết bị. Khi ARM + bấm phím, âm preview phát và VU meter nhảy theo trường độ.' },
+    { title: '🎼 Piano Roll', body: 'Nhấp đúp vào MIDI item để mở Piano Roll. Dùng Ctrl+scroll hoặc nút +/− để zoom. Nhấp để vẽ note, kéo để di chuyển, Ctrl+kéo để copy. Phím tắt: C (vẽ), E (tẩy), Space (nghe).' },
+    { title: '🎛️ FX & Master', body: 'Chọn track → nút FX để mở FX Rack (thêm EQ, compressor...). Bấm nút PWR ở Master để mở Mastering Panel: EQ 4 băng, compressor, limiter. Mọi thay đổi áp dụng realtime.' },
+    { title: '🧪 SoundFont & VST', body: 'Vào Tools → Plugin Manager để quét SoundFont (.sf2/.sf3) và VSTi. Track MIDI dùng SoundFont làm nhạc cụ — chọn instrument từ nút Synth trên track.' },
+    { title: '🤖 AI', body: 'Tools → Config AI Providers để cấu hình API (OpenAI, Gemini, Ollama...). Dùng AI Prompt Generator (nút ✨) để sinh MIDI/ý tưởng; AI MIDI Preset Manager để lưu preset.' },
+    { title: '💾 Lưu & Xuất', body: 'Ctrl+S lưu project (cloud/temp), Ctrl+Shift+S Save As. Export WAV qua nút Export — chọn vùng, format, bitrate rồi Render.' },
+    { title: '⌨️ Phím tắt', body: 'Space: Play/Pause · /: Stop · Ctrl+Z/Y: Undo/Redo · Ctrl+C/X/V: Copy/Cut/Paste · Ctrl+S: Save · Ctrl+N: New · S: Split · Ctrl+E: Edit in new tab · Ctrl+wheel: zoom timeline' },
+  ] : [
+    { title: '🚀 Quick start', body: 'Press Space to Play/Pause. Press / to stop. Use Record (●) to capture audio/MIDI. Add tracks from the Track menu or the "+ Add Track" button.' },
+    { title: '🎹 MIDI & ARM', body: 'Enable the red ARM button on a track to receive keys from a MIDI keyboard. Go to Tools → MIDI Devices to pick your device. When ARM + key press, preview audio plays and the VU meter animates for the note length.' },
+    { title: '🎼 Piano Roll', body: 'Double-click a MIDI item to open the Piano Roll. Use Ctrl+scroll or +/− buttons to zoom. Click to draw notes, drag to move, Ctrl+drag to copy. Shortcuts: C (draw), E (erase), Space (listen).' },
+    { title: '🎛️ FX & Master', body: 'Select a track → FX button to open the FX Rack (EQ, compressor...). Press the PWR button on the Master to open the Mastering Panel: 4-band EQ, compressor, limiter — all realtime.' },
+    { title: '🧪 SoundFont & VST', body: 'Tools → Plugin Manager scans SoundFonts (.sf2/.sf3) and VSTi. MIDI tracks use SoundFonts as instruments — pick one from the Synth button on the track.' },
+    { title: '🤖 AI', body: 'Tools → Config AI Providers to set up APIs (OpenAI, Gemini, Ollama...). Use the AI Prompt Generator (✨) to create MIDI/ideas; AI MIDI Preset Manager stores presets.' },
+    { title: '💾 Save & Export', body: 'Ctrl+S saves the project (cloud/temp), Ctrl+Shift+S Save As. Export WAV via the Export button — pick range, format, bitrate, then Render.' },
+    { title: '⌨️ Shortcuts', body: 'Space: Play/Pause · /: Stop · Ctrl+Z/Y: Undo/Redo · Ctrl+C/X/V: Copy/Cut/Paste · Ctrl+S: Save · Ctrl+N: New · S: Split · Ctrl+E: Edit in new tab · Ctrl+wheel: zoom timeline' },
+  ];
+  return (
+    <div className="fixed inset-0 z-[9999] flex items-center justify-center bg-black/70 backdrop-blur-sm" onClick={onClose}>
+      <div className="bg-[#1e1e24] border border-zinc-700 rounded-xl shadow-2xl w-full max-w-2xl max-h-[85vh] flex flex-col text-slate-200" onClick={e => e.stopPropagation()}>
+        <div className="flex items-center justify-between px-5 py-3 border-b border-zinc-800 shrink-0">
+          <h2 className="text-base font-bold text-white">{vi ? 'Hướng dẫn sử dụng SonicForge Studio' : 'SonicForge Studio User Guide'}</h2>
+          <button onClick={onClose} className="w-6 h-6 rounded hover:bg-zinc-700 text-zinc-400 hover:text-white text-sm">✕</button>
+        </div>
+        <div className="overflow-y-auto px-5 py-4 space-y-3">
+          {sections.map((s, i) => (
+            <div key={i} className="bg-zinc-900/60 border border-zinc-800 rounded-lg p-3">
+              <h3 className="text-sm font-bold text-cyan-400 mb-1">{s.title}</h3>
+              <p className="text-xs text-zinc-300 leading-relaxed">{s.body}</p>
+            </div>
+          ))}
+        </div>
+        <div className="px-5 py-3 border-t border-zinc-800 flex justify-end shrink-0">
+          <button onClick={onClose} className="px-4 py-1.5 bg-cyan-700 hover:bg-cyan-600 rounded text-xs font-bold text-white transition">{vi ? 'Đóng' : 'Close'}</button>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+const PreferencesModal = ({ isOpen, onClose, prefs, onPrefsChange }) => {
+  if (!isOpen) return null;
+  const vi = prefs.language !== 'en';
+  const themes = [
+    { id: 'dark', name: vi ? 'Tối (mặc định)' : 'Dark (default)', swatch: 'from-zinc-700 to-zinc-900', ring: 'ring-cyan-400' },
+    { id: 'midnight', name: vi ? 'Đêm xanh' : 'Midnight', swatch: 'from-sky-800 to-slate-950', ring: 'ring-sky-400' },
+    { id: 'forest', name: vi ? 'Rừng xanh' : 'Forest', swatch: 'from-emerald-700 to-green-950', ring: 'ring-emerald-400' },
+    { id: 'violet', name: vi ? 'Tím' : 'Violet', swatch: 'from-violet-700 to-purple-950', ring: 'ring-violet-400' },
+    { id: 'graphite', name: vi ? 'Than chì' : 'Graphite', swatch: 'from-zinc-600 to-neutral-900', ring: 'ring-zinc-300' },
+  ];
+  const set = (k, v) => onPrefsChange({ ...prefs, [k]: v });
+  return (
+    <div className="fixed inset-0 z-[9999] flex items-center justify-center bg-black/70 backdrop-blur-sm" onClick={onClose}>
+      <div className="bg-[#1e1e24] border border-zinc-700 rounded-xl shadow-2xl w-full max-w-md max-h-[85vh] overflow-y-auto p-5 text-slate-200" onClick={e => e.stopPropagation()}>
+        <div className="flex items-center justify-between mb-4">
+          <h2 className="text-base font-bold text-white">{vi ? 'Tùy chọn (Preferences)' : 'Preferences'}</h2>
+          <button onClick={onClose} className="w-6 h-6 rounded hover:bg-zinc-700 text-zinc-400 hover:text-white text-sm">✕</button>
+        </div>
+
+        {/* Theme */}
+        <div className="mb-5">
+          <h3 className="text-xs font-bold text-zinc-400 uppercase tracking-wider mb-2">{vi ? '🎨 Chủ đề màu' : '🎨 Theme'}</h3>
+          <div className="grid grid-cols-1 gap-1.5">
+            {themes.map(th => (
+              <button key={th.id} onClick={() => set('theme', th.id)}
+                className={`flex items-center gap-2.5 px-2.5 py-2 rounded-lg border text-xs text-left transition ${prefs.theme === th.id ? 'border-cyan-500 bg-zinc-800' : 'border-zinc-700 bg-zinc-900 hover:bg-zinc-800'}`}>
+                <span className={`w-6 h-6 rounded-md bg-gradient-to-br ${th.swatch} ring-1 ring-black/40 shrink-0 ${prefs.theme === th.id ? `ring-2 ${th.ring}` : ''}`}></span>
+                <span className="text-zinc-200">{th.name}</span>
+                {prefs.theme === th.id && <span className="ml-auto text-cyan-400 text-[10px] font-bold">✓</span>}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        {/* Language */}
+        <div className="mb-5">
+          <h3 className="text-xs font-bold text-zinc-400 uppercase tracking-wider mb-2">{vi ? '🌐 Ngôn ngữ' : '🌐 Language'}</h3>
+          <div className="flex gap-1.5">
+            {[{ id: 'vi', label: 'Tiếng Việt' }, { id: 'en', label: 'English' }].map(l => (
+              <button key={l.id} onClick={() => set('language', l.id)}
+                className={`flex-1 px-2 py-1.5 rounded-lg border text-xs font-semibold transition ${prefs.language === l.id ? 'border-cyan-500 bg-cyan-900/40 text-cyan-300' : 'border-zinc-700 bg-zinc-900 text-zinc-400 hover:bg-zinc-800'}`}>
+                {l.label}
+              </button>
+            ))}
+          </div>
+          <p className="text-[10px] text-zinc-500 mt-1">{vi ? 'Áp dụng ngay cho menu & hướng dẫn.' : 'Applies immediately to menus & guide.'}</p>
+        </div>
+
+        {/* Button font size */}
+        <div className="mb-5">
+          <h3 className="text-xs font-bold text-zinc-400 uppercase tracking-wider mb-2">{vi ? '🔠 Cỡ chữ nút bấm' : '🔠 Button font size'}</h3>
+          <div className="flex gap-1.5">
+            {[{ id: 'sm', label: vi ? 'Nhỏ' : 'Small' }, { id: 'md', label: vi ? 'Vừa' : 'Medium' }, { id: 'lg', label: vi ? 'Lớn' : 'Large' }].map(f => (
+              <button key={f.id} onClick={() => set('buttonFontSize', f.id)}
+                className={`flex-1 px-2 py-1.5 rounded-lg border text-xs font-semibold transition ${prefs.buttonFontSize === f.id ? 'border-cyan-500 bg-cyan-900/40 text-cyan-300' : 'border-zinc-700 bg-zinc-900 text-zinc-400 hover:bg-zinc-800'}`}>
+                {f.label}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        <div className="flex justify-end gap-2 pt-2 border-t border-zinc-800">
+          <button onClick={onClose} className="px-3 py-1.5 bg-zinc-700 hover:bg-zinc-600 rounded text-xs font-bold text-white transition">{vi ? 'Hủy' : 'Cancel'}</button>
+          <button onClick={onClose} className="px-4 py-1.5 bg-cyan-700 hover:bg-cyan-600 rounded text-xs font-bold text-white transition">{vi ? 'Lưu & Đóng' : 'Save & Close'}</button>
+        </div>
+      </div>
+    </div>
+  );
+};
+
 const AIPresetModal = ({ isOpen, onClose }) => {
   if (!isOpen) return null;
 
@@ -14273,7 +14552,7 @@ const App = () => {
     setInstrumentDropdownTrackId(null);
     setInstrumentDropdownBtnRect(null);
     setSynthCategory(null);
-    // Trigger SpessaSynth load + program change when soundfont instrument selected
+    // Trigger FluidSynth load + program change when soundfont instrument selected
     if (window.SonicSF && window.SonicSF.selectInstrument && instrumentId && isSfInstrument) {
       const sfId = instrumentId.replace('sf_', '');
       window.SonicSF.selectInstrument(mch, sfBank || 0, sfProg || 0, sfId);
@@ -14500,6 +14779,11 @@ const App = () => {
                           if (window.triggerMidiVuActivity) {
                             window.triggerMidiVuActivity(as.trackId, scaledVel);
                           }
+                          // Giữ VU theo trường độ: tăng counter note đang giữ
+                          // (tick giữ peak cho tới khi note-off)
+                          try {
+                            heldMidiNotesRef.current[as.trackId] = (heldMidiNotesRef.current[as.trackId] || 0) + 1;
+                          } catch (err) { }
                           window.SonicSF.playNote(pitch, scaledVel, 60000, undefined, asProg, null, asCh, asSe);
                        });
                      }
@@ -14512,6 +14796,10 @@ const App = () => {
                         if (window.triggerMidiVuActivity) {
                           window.triggerMidiVuActivity(at.id, scaledVel);
                         }
+                        // Giữ VU theo trường độ: tăng counter note đang giữ
+                        try {
+                          heldMidiNotesRef.current[at.id] = (heldMidiNotesRef.current[at.id] || 0) + 1;
+                        } catch (err) { }
                         window.SonicSF.playNote(pitch, scaledVel, 60000, undefined, atProg, atDest, atCh, atSe);
                      });
                    }
@@ -14535,6 +14823,16 @@ const App = () => {
                      if (!st.synth_engine && st.midiChannel === undefined) return;
                      var stCh = assignTrackMidiChannel(st, stopTracks);
                      window.SonicSF.stopNote(stCh, pitch);
+                     // Giảm counter note đang giữ — hết note → VU được phép decay/tắt
+                     // (tick sẽ thấy counter = 0 và không còn giữ peak nữa)
+                     try {
+                       if (heldMidiNotesRef.current[st.id] !== undefined) {
+                         heldMidiNotesRef.current[st.id] = Math.max(0, heldMidiNotesRef.current[st.id] - 1);
+                         if (heldMidiNotesRef.current[st.id] === 0) {
+                           delete heldMidiNotesRef.current[st.id];
+                         }
+                       }
+                     } catch (err) { }
                    });
                  }
               }
@@ -15494,6 +15792,11 @@ const App = () => {
   }, [isPlaying]);
 
   const midiVuActivityRef = useRef({});
+  // Đếm số note MIDI đang GIỮ per-track (ARM + MIDI keyboard live input).
+  // VU tick dùng ref này: còn note giữ → giữ peak (không decay) → VU animate
+  // ĐÚNG trường độ âm thanh (user bug: nhấn phím giữ âm còn kêu nhưng VU tắt
+  // sau ~0.5s vì decay 0.75/frame). Hết note (note-off) → mới decay/tắt.
+  const heldMidiNotesRef = useRef({});
   const triggerMidiVuActivity = (trackId, velocity) => {
     if (!trackId) return;
     const velFactor = typeof velocity === 'number' ? (velocity > 1 ? velocity / 127 : velocity) : 0.8;
@@ -15538,6 +15841,51 @@ const App = () => {
   const [aiPresetModalOpen, setAiPresetModalOpen] = useState(false);
   const [aiPresetVersion, setAiPresetVersion] = useState(0);
   const [showMasteringModal, setShowMasteringModal] = useState(false);
+  // ── Help / About / Preferences (menu Help + Tools) ──
+  const [aboutModalOpen, setAboutModalOpen] = useState(false);
+  const [helpModalOpen, setHelpModalOpen] = useState(false);
+  const [preferencesModalOpen, setPreferencesModalOpen] = useState(false);
+  const [prefs, setPrefs] = useState(() => {
+    try {
+      const saved = localStorage.getItem('sf_prefs');
+      if (saved) return JSON.parse(saved);
+    } catch (e) { }
+    return { theme: 'dark', language: 'vi', buttonFontSize: 'md' };
+  });
+  // Áp dụng theme + font size lên <html> ngay khi đổi
+  useEffect(() => {
+    try {
+      document.documentElement.setAttribute('data-theme', prefs.theme || 'dark');
+      document.documentElement.setAttribute('data-btnfont', prefs.buttonFontSize || 'md');
+      localStorage.setItem('sf_prefs', JSON.stringify(prefs));
+    } catch (e) { }
+  }, [prefs]);
+  // Load preferences từ server (nếu có tài khoản) khi khởi động
+  useEffect(() => {
+    let cancelled = false;
+    if (window.SonicAPI && window.SonicAPI.getPreferences) {
+      window.SonicAPI.getPreferences().then(res => {
+        if (cancelled || !res || !res.success || !res.preferences) return;
+        const p = res.preferences;
+        if (p.theme || p.language || p.buttonFontSize) {
+          setPrefs(prev => ({
+            theme: p.theme || prev.theme,
+            language: p.language || prev.language,
+            buttonFontSize: p.buttonFontSize || prev.buttonFontSize
+          }));
+        }
+      }).catch(() => { });
+    }
+    return () => { cancelled = true; };
+  }, []);
+  // Lưu preferences lên server khi đổi
+  const handlePrefsChange = (next) => {
+    setPrefs(next);
+    try { localStorage.setItem('sf_prefs', JSON.stringify(next)); } catch (e) { }
+    if (window.SonicAPI && window.SonicAPI.savePreferences) {
+      window.SonicAPI.savePreferences(next).catch(() => { });
+    }
+  };
   // Unified FX Rack target context (unified_fx_rack_panel.md): { trackId, trackName } | null
   const [fxRackTarget, setFxRackTarget] = useState(null);
   window.__openFxRack = (trackId, trackName) => setFxRackTarget({ trackId, trackName });
@@ -17782,6 +18130,33 @@ const App = () => {
       for (let i = 0; i < endSample - startSample; i++) {
         resultData[startSample + i] = i < subResampled.length ? subResampled[i] : 0.0;
       }
+    } else if (effectType === 'invert_phase') {
+      // DSP: đảo pha — nhân -1 toàn bộ vùng chọn/clip
+      for (let i = startSample; i < endSample; i++) {
+        resultData[i] = -resultData[i];
+      }
+    } else if (effectType === 'swap_channels') {
+      // DSP: đảo kênh L/R — buffer 2 kênh (nếu có), hoán đổi dữ liệu
+      const srcBuffer = subTab.buffer;
+      if (srcBuffer.numberOfChannels >= 2) {
+        const l = srcBuffer.getChannelData(0).slice();
+        const r = srcBuffer.getChannelData(1).slice();
+        const out = ctx.createBuffer(2, eff.length, sr);
+        out.getChannelData(0).set(r);
+        out.getChannelData(1).set(l);
+        resultBuffer = out;
+        resultData = resultBuffer.getChannelData(0);
+      } else {
+        // Mono → không đổi kênh được, giữ nguyên
+        showToast('Buffer mono — không có kênh L/R để hoán đổi.', 'info');
+        return;
+      }
+    } else if (effectType === 'reverse') {
+      // DSP: đảo ngược thời gian vùng chọn/clip
+      const seg = resultData.slice(startSample, endSample);
+      for (let i = 0; i < seg.length; i++) {
+        resultData[startSample + i] = seg[seg.length - 1 - i];
+      }
     }
 
     // Update subTab buffer state
@@ -17794,7 +18169,11 @@ const App = () => {
         selectionEnd: null
       };
     }));
-    showToast(`Đã áp dụng ${effectType === 'normalize' ? 'Normalize' : effectType === 'gain' ? 'Gain' : 'Pitch'} cho ${hasSelection ? 'vùng chọn' : 'toàn bộ clip'}.`, 'success');
+    const effectLabels = {
+      normalize: 'Normalize', gain: 'Gain', pitch: 'Pitch',
+      invert_phase: 'Phase Invert', swap_channels: 'Swap L/R', reverse: 'Reverse'
+    };
+    showToast(`Đã áp dụng ${effectLabels[effectType] || effectType} cho ${hasSelection ? 'vùng chọn' : 'toàn bộ clip'}.`, 'success');
   };
   const exportSubTabBuffer = async tabId => {
     const subTab = subTabs.find(s => s.id === tabId);
@@ -20595,6 +20974,9 @@ const App = () => {
     // âm cũ — user 06:45: tắt âm MAIN items khi vào SECTION-TAB → VU main
     // items phải tắt theo, không "diễn" tiếp).
     try { midiVuActivityRef.current = {}; } catch (e) { }
+    // Clear luôn counter note đang giữ — nếu không, sau stop (âm đã dừng)
+    // tick vẫn thấy heldCnt > 0 → giữ peak → VU dính mãi (user bug 08:08).
+    try { heldMidiNotesRef.current = {}; } catch (e) { }
     stopMidiCapture();
     if (window.SonicSF) {
       try { window.SonicSF.stopAll(); } catch (e) { console.warn('[Stop] stopAll error:', e); }
@@ -25744,8 +26126,18 @@ STRICT CONSTRAINTS:
       try {
       // Khi STOP (không play, không recording): vẽ VU RỖNG — không đọc analyser/
       // activity → hết animation dính + master không full sau khi dừng play.
+      // ⚠️ NGOẠI LỆ: nếu có MIDI activity live (bật ARM track + bấm phím MIDI
+      // keyboard — KHÔNG play/record) thì KHÔNG early-return — track VU phải
+      // nhảy theo midiVuActivityRef + decay (user bug: ARM + phím MIDI → VU
+      // đứng yên vì block này vẽ rỗng và return trước khi đọc activity).
       const isRecActive = activeAudioRecordersRef.current && Object.keys(activeAudioRecordersRef.current).length > 0;
-      if (!isPlaying && !isRecActive) {
+      let liveMidiVu = false;
+      try {
+        for (const _k in midiVuActivityRef.current) {
+          if (midiVuActivityRef.current[_k] > 0.001) { liveMidiVu = true; break; }
+        }
+      } catch (e) { }
+      if (!isPlaying && !isRecActive && !liveMidiVu) {
         setMasterVU(0);
         setMasterMeterPeak(0);
         Object.keys(trackVuRefs.current).forEach(k => {
@@ -25846,12 +26238,18 @@ STRICT CONSTRAINTS:
         // velocity thấp (âm SF nhỏ < 0.03) → VU không nhảy (user bug 07:10).
         let midiPeak = isAudible ? (midiVuActivityRef.current[vuKey] || 0) : 0;
         if (midiPeak > 0) {
-          // Decay 0.75 (~0.5s) — cân bằng: note đơn/velocity thấp hiển thị rõ
+          // ARM + MIDI keyboard: còn note đang GIỮ → giữ nguyên peak, KHÔNG
-          // NHƯNG tắt nhanh sau hết note (decay 0.85 ~1s quá lâu — user:
+          // decay → VU animate đúng trường độ âm thanh (user bug 08:08: âm còn
-          // "vẫn diễn animation" sau khi âm hết — bug 07:15).
+          // kêu nhưng VU tắt sau ~0.5s vì decay 0.75/frame). Hết note → decay
-          midiVuActivityRef.current[vuKey] = midiPeak * 0.75;
+          // 0.75 (~0.5s) tắt nhanh như trước.
-          if (midiVuActivityRef.current[vuKey] < 0.01) {
+          const heldCnt = heldMidiNotesRef.current[vuKey] || 0;
-            midiVuActivityRef.current[vuKey] = 0;
+          if (heldCnt > 0) {
+            // Giữ nguyên peak trong khi âm đang kêu (không decay)
+          } else {
+            midiVuActivityRef.current[vuKey] = midiPeak * 0.75;
+            if (midiVuActivityRef.current[vuKey] < 0.01) {
+              midiVuActivityRef.current[vuKey] = 0;
+            }
           }
         }
         // ⚠️ KHÔNG gộp sfAudioPeak vào audioPeak: SF là 1 output CHUNG cho mọi
@@ -26229,7 +26627,17 @@ STRICT CONSTRAINTS:
     }, {
       label: 'DSP Tools Panel',
       icon: 'wrench',
-      action: () => openPanel('python_tools')
+      action: () => {
+        // DSP Tool đã được move vào SUB-TAB editor (audioclip). Mở sub-tab
+        // edit cho track/clip đang chọn — nếu chưa có clip → mở panel cũ.
+        const t = activeTracks.find(x => x.id === selectedTrackId);
+        if (t && (t.buffer || (t.clips && t.clips.length))) {
+          const clipId = (t.clips && t.clips[0]) ? t.clips[0].id : 'default';
+          handleEditClipInSubTab(t.id, clipId);
+        } else {
+          openPanel('python_tools');
+        }
+      }
     }, {
       sep: true
     }, {
@@ -26239,13 +26647,25 @@ STRICT CONSTRAINTS:
         setPluginManagerModalOpen(true);
         window.SonicAPI.listPlugins().then(data => setPluginsData(data)).catch(() => {});
       }
+    }, {
+      sep: true
+    }, {
+      label: 'Preferences...',
+      icon: 'settings-2',
+      action: () => setPreferencesModalOpen(true)
     }]
   }, {
     label: 'Help',
     items: [{
-      label: 'About SonicForge',
+      label: 'Hướng dẫn sử dụng...',
+      icon: 'book-open',
+      action: () => setHelpModalOpen(true)
+    }, {
+      sep: true
+    }, {
+      label: 'About SonicForge Studio...',
       icon: 'info',
-      action: () => showToast('SonicForge Studio v1.0 - Professional DAW', 'info')
+      action: () => setAboutModalOpen(true)
     }]
   }].map(menu => /*#__PURE__*/React.createElement("div", {
     key: menu.label,
@@ -28291,6 +28711,36 @@ STRICT CONSTRAINTS:
         className: "w-12 bg-black text-amber-300 text-[14px] px-1 py-0.5 rounded border border-zinc-700 text-center font-mono",
         title: "Loop count"
       }))), /*#__PURE__*/React.createElement("div", {
+        className: "flex items-center justify-between text-[14px] text-zinc-500 mb-1 font-semibold uppercase mt-2"
+      }, /*#__PURE__*/React.createElement("span", null, "DSP"), /*#__PURE__*/React.createElement("span", {
+        className: "font-mono text-zinc-600 text-[11px] normal-case"
+      }, "áp dụng vùng chọn / cả clip")), /*#__PURE__*/React.createElement("div", {
+        className: "grid grid-cols-3 gap-1 mb-2"
+      }, /*#__PURE__*/React.createElement("button", {
+        onClick: () => applySubTabEffect(st.id, 'invert_phase', 0),
+        className: "py-1 bg-sky-900 hover:bg-sky-800 text-sky-200 font-bold rounded text-[14px] border border-sky-700 flex items-center justify-center gap-1"
+      }, /*#__PURE__*/React.createElement("span", {
+        className: "inline-flex items-center shrink-0"
+      }, /*#__PURE__*/React.createElement("i", {
+        "data-lucide": "arrow-down-up",
+        className: "w-3 h-3"
+      })), "Phase Inv"), /*#__PURE__*/React.createElement("button", {
+        onClick: () => applySubTabEffect(st.id, 'swap_channels', 0),
+        className: "py-1 bg-sky-900 hover:bg-sky-800 text-sky-200 font-bold rounded text-[14px] border border-sky-700 flex items-center justify-center gap-1"
+      }, /*#__PURE__*/React.createElement("span", {
+        className: "inline-flex items-center shrink-0"
+      }, /*#__PURE__*/React.createElement("i", {
+        "data-lucide": "shuffle",
+        className: "w-3 h-3"
+      })), "Swap L/R"), /*#__PURE__*/React.createElement("button", {
+        onClick: () => applySubTabEffect(st.id, 'reverse', 0),
+        className: "py-1 bg-sky-900 hover:bg-sky-800 text-sky-200 font-bold rounded text-[14px] border border-sky-700 flex items-center justify-center gap-1"
+      }, /*#__PURE__*/React.createElement("span", {
+        className: "inline-flex items-center shrink-0"
+      }, /*#__PURE__*/React.createElement("i", {
+        "data-lucide": "arrow-left-right",
+        className: "w-3 h-3"
+      })), "Reverse")), /*#__PURE__*/React.createElement("div", {
         className: "flex gap-1 justify-between my-2.5"
       }, /*#__PURE__*/React.createElement("div", {
         className: "flex flex-col items-center bg-zinc-900/60 p-1.5 rounded border border-zinc-800 flex-1"
@@ -28850,7 +29300,9 @@ STRICT CONSTRAINTS:
     className: "w-3 h-3 text-zinc-600"
   })), prHint ? /*#__PURE__*/React.createElement("span", {
     className: "text-cyan-400"
-  }, prHint) : " Scroll: Zoom"))), contextMenu && (contextMenu.isSubTab ? /*#__PURE__*/React.createElement("div", {
+  }, prHint) : /*#__PURE__*/React.createElement("span", {
+    className: "text-zinc-600 italic"
+  }, "Adaptive tips: hover vào vùng làm việc để xem hướng dẫn")))), contextMenu && (contextMenu.isSubTab ? /*#__PURE__*/React.createElement("div", {
     className: "fixed z-[60] bg-[#2a2a2a] border border-zinc-700 rounded-lg shadow-2xl py-1 w-64 overflow-y-auto",
     style: {
       left: Math.min(contextMenu.x, window.innerWidth - 260),
@@ -29221,6 +29673,18 @@ STRICT CONSTRAINTS:
       const active = providers.find(p => p.is_active) || providers[0];
       if (active) setSelectedProviderId(active.id);
     }
+  }), /*#__PURE__*/React.createElement(AboutModal, {
+    isOpen: aboutModalOpen,
+    onClose: () => setAboutModalOpen(false)
+  }), /*#__PURE__*/React.createElement(HelpModal, {
+    isOpen: helpModalOpen,
+    onClose: () => setHelpModalOpen(false),
+    lang: prefs.language
+  }), /*#__PURE__*/React.createElement(PreferencesModal, {
+    isOpen: preferencesModalOpen,
+    onClose: () => setPreferencesModalOpen(false),
+    prefs: prefs,
+    onPrefsChange: handlePrefsChange
   }), /*#__PURE__*/React.createElement(SystemManagerModal, {
     isOpen: systemManagerModalOpen,
     onClose: () => setSystemManagerModalOpen(false)

app/static/js/services/api.js

@@ -64,6 +64,9 @@ 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' }),
+        getPluginDirs: () => apiRequest('/api/v1/plugins/dirs', { method: 'GET' }),
+        savePluginDirs: (dirs) => apiRequest('/api/v1/plugins/dirs', { method: 'POST', body: JSON.stringify(dirs) }),
+        scanPluginDirs: () => apiRequest('/api/v1/plugins/scan', { method: 'POST' }),
         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' }),

app/tasks/worker.py

@@ -27,6 +27,16 @@ celery_app.conf.update(
     enable_utc=True,
 )
 
+# Che do desktop (SF_DESKTOP=1, do desktop_engine.py set): chay task dong bo
+# trong tien trinh (eager) — ban Standalone Windows KHONG kem Redis broker.
+if os.getenv("SF_DESKTOP") == "1":
+    celery_app.conf.update(
+        task_always_eager=True,
+        task_eager_propagates=True,
+        broker_url="memory://",
+        result_backend="cache+memory://",
+    )
+
 # ── Lịch trình tự động dọn dẹp file hết hạn (Week 5) ──
 celery_app.conf.beat_schedule = {
     "cleanup-expired-files-every-hour": {

app/templates/index.html

@@ -3,8 +3,27 @@
 
 <head>
     <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
     <title>SonicForge Studio - Professional DAW Editor</title>
+    <script>
+        // ── Chặn BROWSER ZOOM toàn trang ──
+        // UI dùng px cố định cho item/button/label — browser zoom (Ctrl+wheel,
+        // Ctrl+plus/minus/0, pinch) scale TOÀN BỘ làm control phóng to theo.
+        // Chặn ở capture phase bằng preventDefault() (KHÔNG stopPropagation —
+        // các vùng zoom chuyên dụng: timeline, piano roll, canvas, EQ vẫn nhận
+        // event và tự xử lý zoom nội dung của chúng).
+        document.addEventListener('wheel', function (e) {
+            if (e.ctrlKey || e.metaKey) e.preventDefault();
+        }, { capture: true, passive: false });
+        document.addEventListener('keydown', function (e) {
+            if ((e.ctrlKey || e.metaKey) && ['+', '-', '=', '_', '0'].indexOf(e.key) !== -1) {
+                e.preventDefault();
+            }
+        }, { capture: true });
+        // Pinch zoom (Safari/WebKit gesture events)
+        document.addEventListener('gesturestart', function (e) { e.preventDefault(); }, { passive: false });
+        document.addEventListener('gesturechange', function (e) { e.preventDefault(); }, { passive: false });
+    </script>
     <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>
@@ -24,7 +43,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/undoRedoEngine.js?v=202607290941"></script>
-    <script src="/static/js/app.precompiled.js?v=202608070950" defer></script>
+    <script src="/static/js/app.precompiled.js?v=202608081600" defer></script>
     <link rel="stylesheet" href="/static/css/styles.css?v=202607271016">
     <style>
         :root {
@@ -33,8 +52,43 @@
             --top-bar-height: 80px;
             --status-bar-height: 25px;
             --panel-border-color: #2a2a2a;
+            /* Theme (Preferences) — có thể override bằng data-theme trên <html> */
+            --sf-bg: #1e1e1e;
+            --sf-panel: #262626;
+            --sf-header: #2e2e2e;
+            --sf-border: #181818;
+            --sf-accent: #00ffcc;
         }
 
+        /* ── THEME presets (Tools → Preferences) ── */
+        html[data-theme="dark"] {
+            --sf-bg: #1e1e1e; --sf-panel: #262626; --sf-header: #2e2e2e; --sf-border: #181818; --sf-accent: #00ffcc;
+        }
+        html[data-theme="midnight"] {
+            --sf-bg: #0f172a; --sf-panel: #1e293b; --sf-header: #1e293b; --sf-border: #0f172a; --sf-accent: #38bdf8;
+        }
+        html[data-theme="forest"] {
+            --sf-bg: #111c15; --sf-panel: #1b2a1e; --sf-header: #1e2d21; --sf-border: #0c1510; --sf-accent: #34d399;
+        }
+        html[data-theme="violet"] {
+            --sf-bg: #170f26; --sf-panel: #221537; --sf-header: #251640; --sf-border: #110a1c; --sf-accent: #a78bfa;
+        }
+        html[data-theme="graphite"] {
+            --sf-bg: #18181b; --sf-panel: #232327; --sf-header: #27272a; --sf-border: #101012; --sf-accent: #e4e4e7;
+        }
+
+        /* Áp theme lên các vùng chính của app shell */
+        .daw-app-shell { background-color: var(--sf-bg) !important; }
+        .daw-panel { background-color: var(--sf-panel) !important; }
+        .daw-header { background-color: var(--sf-header) !important; }
+        body { background-color: var(--sf-bg) !important; }
+        ::-webkit-scrollbar-thumb { background: var(--sf-accent); }
+
+        /* ── BUTTON FONT SIZE (Tools → Preferences) ── */
+        html[data-btnfont="sm"] button { font-size: 10px !important; }
+        html[data-btnfont="md"] button { font-size: 12px !important; }
+        html[data-btnfont="lg"] button { font-size: 14px !important; }
+
         body {
             background-color: #1a1a1a;
             color: #c0c0c0;

build_windows.ps1

@@ -0,0 +1,89 @@
+# build_windows.ps1 - ONE-COMMAND build: daw_engine.exe (PyInstaller) + Tauri v2 (NSIS + MSI)
+# Chay tren Windows:  powershell -ExecutionPolicy Bypass -File build_windows.ps1
+# LUU Y: file nay chi dung ky tu ASCII (khong dau, khong em-dash) - PowerShell 5.1
+# doc .ps1 khong BOM theo ANSI, ky tu Unicode bi hong -> "String is missing terminator".
+$ErrorActionPreference = "Stop"
+Set-Location $PSScriptRoot
+
+# Kill moi daw_engine con song tu build/truoc (windowed, khong console ->
+# de quen -> file exe dang chay bi khoa -> Tauri build loi PermissionDenied
+# khi doc externalBin). Stop-Process im lang neu khong co tien trinh nao.
+Write-Host "== [0/6] Kill daw_engine.exe cu (neu dang chay) =="
+Get-Process -Name "daw_engine" -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue
+Start-Sleep -Milliseconds 500
+
+Write-Host "== [1/6] Python dependencies =="
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt pyinstaller pywin32
+
+Write-Host "== [2/6] Frontend bundle (app.jsx -> app.precompiled.js) =="
+npm install
+# Dam bao @babel/standalone co (build.mjs import truc tiep - da gap
+# ERR_MODULE_NOT_FOUND tren may Windows khi package.json cu thieu dep).
+if (-not (Test-Path "node_modules\@babel\standalone")) {
+  Write-Host "Thieu @babel/standalone - dang cai them..."
+  npm install @babel/standalone --no-audit --no-fund
+}
+if (-not (Test-Path "node_modules\@babel\standalone")) {
+  Write-Host "ERROR: Khong cai duoc @babel/standalone. Kiem tra ket noi npm!" -ForegroundColor Red
+  exit 1
+}
+node build.mjs   # @babel/standalone; thay cho 'npm run build' (Babel 8 ESM-only CLI conflict)
+
+Write-Host "== [3/6] Build daw_engine.exe (PyInstaller) =="
+pyinstaller engine.spec --clean --noconfirm
+
+Write-Host "== [3.5/6] Verify bundle contents (app/static, app/templates phai co) =="
+# Bat loi bundle NGAY tai build (da gap 2 lan: chay pyinstaller tu noi khac
+# -> static/templates thieu -> exe crash 'Directory ...\app\static does not exist').
+# Dung tools/verify_bundle.py (parse TOC bang ast, chap nhan ca / va \) thay
+# vi regex thong thuong (TOC Windows co the dung backslash -> false positive).
+# Truoc tien kiem tra engine.spec phai la ban moi (collect_data_files).
+$specContent = Get-Content "engine.spec" -Raw -ErrorAction SilentlyContinue
+if ($specContent -notmatch "collect_data_files\('app'") {
+  Write-Host "ERROR: engine.spec CU (thieu collect_data_files('app')). Pull code moi truoc khi build!" -ForegroundColor Red
+  exit 1
+}
+python tools\verify_bundle.py
+if ($LASTEXITCODE -ne 0) {
+  Write-Host "ERROR: Bundle thieu asset - dung build, kiem tra engine.spec datas!" -ForegroundColor Red
+  exit 1
+}
+
+Write-Host "== [4/6] ONEDIR engine -> src-tauri/resources/daw_engine (Tauri resources) =="
+# ONEDIR: copy ca thu muc dist\daw_engine\ (exe + _internal) vao resources.
+# Tauri bundle resources -> resource_dir()/daw_engine/daw_engine.exe luc runtime.
+if (-not (Test-Path "dist\daw_engine\daw_engine.exe")) {
+  Write-Host "ERROR: dist\daw_engine\daw_engine.exe khong ton tai (onedir build loi?)" -ForegroundColor Red
+  exit 1
+}
+if (Test-Path "src-tauri\resources\daw_engine") {
+  Remove-Item -Recurse -Force "src-tauri\resources\daw_engine"
+}
+New-Item -ItemType Directory -Force "src-tauri\resources\daw_engine" | Out-Null
+Copy-Item "dist\daw_engine\*" "src-tauri\resources\daw_engine\" -Recurse -Force
+Write-Host "Copied onedir engine -> src-tauri\resources\daw_engine"
+
+Write-Host "== [5/6] VC++ Redistributable cho hooks.nsh =="
+if (-not (Test-Path src-tauri\vc_redist.x64.exe)) {
+  Invoke-WebRequest -Uri "https://aka.ms/vs/17/release/vc_redist.x64.exe" -OutFile src-tauri\vc_redist.x64.exe
+}
+
+Write-Host "== [6/6] Tauri build (NSIS .exe + MSI) =="
+# Guard: resources/daw_engine PHAI co exe + _internal truoc khi tauri build
+# (glob trong tauri.conf.json fail ngay "path not found" neu thieu).
+if (-not (Test-Path "src-tauri\resources\daw_engine\daw_engine.exe")) {
+  Write-Host "ERROR: src-tauri\resources\daw_engine\daw_engine.exe khong co - buoc [4/6] that bai?" -ForegroundColor Red
+  exit 1
+}
+if (-not (Test-Path "src-tauri\resources\daw_engine\_internal")) {
+  Write-Host "ERROR: thieu src-tauri\resources\daw_engine\_internal (onedir khong day du)" -ForegroundColor Red
+  exit 1
+}
+npm install -D @tauri-apps/cli
+npx tauri build
+
+Write-Host ""
+Write-Host "== DONE =="
+Write-Host "  NSIS: src-tauri\target\release\bundle\nsis\SonicForgeDAW_1.0.0_x64-setup.exe"
+Write-Host "  MSI : src-tauri\target\release\bundle\msi\SonicForgeDAW_1.0.0_x64_en-US.msi"

desktop_engine.py

@@ -0,0 +1,116 @@
+"""SonicForge DAW — Desktop engine launcher (PyInstaller entry point).
+
+Chay FastAPI backend duoi dang tien trinh nen (sidecar) cho ban cai Standalone
+Windows (Tauri v2 shell). Tu chon port 8000-8010 (fallback neu bi chiem), tu
+thoat khi tien trinh cha (Tauri) ket thuc — Graceful Shutdown.
+"""
+import logging
+import os
+import socket
+import sys
+import threading
+import time
+
+PORT_RANGE = (8000, 8010)
+APP_DATA_DIR_NAME = "SonicForgeDAW"
+
+
+def _pick_port():
+    for port in range(PORT_RANGE[0], PORT_RANGE[1] + 1):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                s.bind(("127.0.0.1", port))
+                return port
+            except OSError:
+                continue
+    return PORT_RANGE[0]
+
+
+def _parent_alive(pid):
+    # Windows: os.kill(pid, 0) KHONG kiem tra ton tai — no goi
+    # TerminateProcess (giai thich: moi sig khac CTRL_C/BREAK deu terminate).
+    # => watchdog se GIET LUON tien trinh cha (Tauri) sau 1s dau tien.
+    # Dung OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION): tra ve NULL khi
+    # pid khong con ton tai.
+    if os.name == "nt":
+        import ctypes
+        PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        h = ctypes.windll.kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+        if not h:
+            return False  # tien trinh da chet
+        ctypes.windll.kernel32.CloseHandle(h)
+        return True
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
+def main():
+    os.environ.setdefault("SF_DESKTOP", "1")
+
+    # Log dir tao SOM de stderr co the tro vao file (xem duoi).
+    log_dir = os.path.join(
+        os.environ.get("APPDATA") or os.path.expanduser("~"),
+        APP_DATA_DIR_NAME, "logs",
+    )
+    try:
+        os.makedirs(log_dir, exist_ok=True)
+    except OSError:
+        log_dir = os.path.expanduser("~")
+
+    # Windowed app (engine.spec console=False): Windows khong tao console ->
+    # sys.stdout/sys.stderr = None -> uvicorn logging crash
+    # ('NoneType' object has no attribute 'isatty'). Tro stdout/stderr vao
+    # FILE (KHONG phai devnull) — neu devnull thi moi exception bi nuot im
+    # lang (trieu chung 'stuck khong logs, khong loi').
+    if sys.stdout is None:
+        sys.stdout = open(os.path.join(log_dir, "stdout.log"), "w", encoding="utf-8")
+    if sys.stderr is None:
+        sys.stderr = open(os.path.join(log_dir, "stderr.log"), "w", encoding="utf-8")
+
+    port = _pick_port()
+    os.environ["SF_PORT"] = str(port)
+
+    # Log ra file — khi dong goi console=False, stdout khong nhin thay duoc.
+    try:
+        logging.basicConfig(
+            level=logging.INFO,
+            format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+            handlers=[
+                logging.FileHandler(os.path.join(log_dir, "engine.log"), encoding="utf-8"),
+                logging.StreamHandler(),
+            ],
+        )
+    except Exception:
+        logging.basicConfig(level=logging.INFO)
+
+    import uvicorn
+    import app.main  # noqa: F401 — import tuong minh de PyInstaller bundle du package app
+
+    config = uvicorn.Config(app.main.app, host="127.0.0.1", port=port,
+                            log_level="info", access_log=False)
+    server = uvicorn.Server(config)
+
+    parent_pid = os.environ.get("SF_PARENT_PID")
+    if parent_pid:
+        def _watchdog():
+            pid = int(parent_pid)
+            while True:
+                time.sleep(1.0)
+                if not _parent_alive(pid):
+                    logging.getLogger("desktop_engine").info(
+                        "Parent process exited — shutting down engine")
+                    server.should_exit = True
+                    return
+        threading.Thread(target=_watchdog, daemon=True).start()
+
+    logging.getLogger("desktop_engine").info(
+        "SonicForge engine listening on 127.0.0.1:%d", port)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

docker-compose.prod.yml

@@ -0,0 +1,58 @@
+# ── Production compose — KHÔNG mount source, image từ registry, bí mật qua .env ──
+# Dùng:  docker compose -f docker-compose.prod.yml up -d
+services:
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+
+  web:
+    image: ${IMAGE:-sonicforge-studio:latest}
+    restart: unless-stopped
+    ports:
+      - "${WEB_PORT:-8000}:8000"
+    env_file: .env
+    volumes:
+      - sf_uploads:/app/app/storage/uploads
+      - sf_processed:/app/app/storage/processed
+      - sf_db:/app/app/storage
+      - ${VST3_DIR:-./vst_plugins}:/opt/daw_engine/vst3:ro
+      - ${SOUNDFONTS_DIR:-./soundfonts}:/opt/daw_engine/soundfonts:ro
+      - ${PIANOBOOK_DIR:-./samples/pianobook}:/opt/daw_engine/samples/pianobook:ro
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request;urllib.request.urlopen('http://localhost:8000/health')"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 15s
+    depends_on:
+      - redis
+
+  worker:
+    image: ${IMAGE:-sonicforge-studio:latest}
+    restart: unless-stopped
+    command: celery -A app.tasks.worker.celery_app worker --loglevel=info
+    env_file: .env
+    volumes:
+      - sf_uploads:/app/app/storage/uploads
+      - sf_processed:/app/app/storage/processed
+      - sf_db:/app/app/storage
+      - ${VST3_DIR:-./vst_plugins}:/opt/daw_engine/vst3:ro
+      - ${SOUNDFONTS_DIR:-./soundfonts}:/opt/daw_engine/soundfonts:ro
+      - ${PIANOBOOK_DIR:-./samples/pianobook}:/opt/daw_engine/samples/pianobook:ro
+    depends_on:
+      - redis
+
+  beat:
+    image: ${IMAGE:-sonicforge-studio:latest}
+    restart: unless-stopped
+    command: celery -A app.tasks.worker.celery_app beat --loglevel=info
+    env_file: .env
+    volumes:
+      - sf_db:/app/app/storage
+    depends_on:
+      - redis
+
+volumes:
+  sf_uploads:
+  sf_processed:
+  sf_db:

docker-compose.yml

@@ -10,13 +10,15 @@ services:
       - "8000:8000"
     volumes:
       - .:/app
-      - /home/locpham/daw_assets/vst3:/opt/daw_engine/vst3
+      - ${VST_DIR:-/home/locpham/daw_assets/vst3}:/opt/daw_engine/vst3
-      - /home/locpham/daw_assets/soundfonts:/opt/daw_engine/soundfonts
+      - ${SOUNDFONT_DIR:-/home/locpham/daw_assets/soundfonts}:/opt/daw_engine/soundfonts
-      - /home/locpham/daw_assets/pianobook:/opt/daw_engine/samples/pianobook
+      - ${PIANOBK_DIR:-/home/locpham/daw_assets/pianobook}:/opt/daw_engine/samples/pianobook
     environment:
       - REDIS_URL=redis://redis:6379/0
       - CELERY_BROKER_URL=redis://redis:6379/0
       - CELERY_RESULT_BACKEND=redis://redis:6379/0
+      - VST_DIR=/opt/daw_engine/vst3
+      - SOUNDFONT_DIR=/opt/daw_engine/soundfonts
     depends_on:
       - redis
 
@@ -25,13 +27,15 @@ services:
     command: celery -A app.tasks.worker.celery_app worker --loglevel=info
     volumes:
       - .:/app
-      - /home/locpham/daw_assets/vst3:/opt/daw_engine/vst3
+      - ${VST_DIR:-/home/locpham/daw_assets/vst3}:/opt/daw_engine/vst3
-      - /home/locpham/daw_assets/soundfonts:/opt/daw_engine/soundfonts
+      - ${SOUNDFONT_DIR:-/home/locpham/daw_assets/soundfonts}:/opt/daw_engine/soundfonts
-      - /home/locpham/daw_assets/pianobook:/opt/daw_engine/samples/pianobook
+      - ${PIANOBK_DIR:-/home/locpham/daw_assets/pianobook}:/opt/daw_engine/samples/pianobook
     environment:
       - REDIS_URL=redis://redis:6379/0
       - CELERY_BROKER_URL=redis://redis:6379/0
       - CELERY_RESULT_BACKEND=redis://redis:6379/0
+      - VST_DIR=/opt/daw_engine/vst3
+      - SOUNDFONT_DIR=/opt/daw_engine/soundfonts
     depends_on:
       - redis
 
@@ -40,12 +44,14 @@ services:
     command: celery -A app.tasks.worker.celery_app beat --loglevel=info
     volumes:
       - .:/app
-      - /home/locpham/daw_assets/vst3:/opt/daw_engine/vst3
+      - ${VST_DIR:-/home/locpham/daw_assets/vst3}:/opt/daw_engine/vst3
-      - /home/locpham/daw_assets/soundfonts:/opt/daw_engine/soundfonts
+      - ${SOUNDFONT_DIR:-/home/locpham/daw_assets/soundfonts}:/opt/daw_engine/soundfonts
-      - /home/locpham/daw_assets/pianobook:/opt/daw_engine/samples/pianobook
+      - ${PIANOBK_DIR:-/home/locpham/daw_assets/pianobook}:/opt/daw_engine/samples/pianobook
     environment:
       - REDIS_URL=redis://redis:6379/0
       - CELERY_BROKER_URL=redis://redis:6379/0
       - CELERY_RESULT_BACKEND=redis://redis:6379/0
+      - VST_DIR=/opt/daw_engine/vst3
+      - SOUNDFONT_DIR=/opt/daw_engine/soundfonts
     depends_on:
       - redis

engine.spec

@@ -0,0 +1,139 @@
+# engine.spec — PyInstaller config cho daw_engine.exe (sidecar Python)
+# Chay: pyinstaller engine.spec --clean --noconfirm (tren Windows)
+# -*- mode: python ; coding: utf-8 -*-
+
+import os
+from PyInstaller.utils.hooks import collect_dynamic_libs, collect_submodules, collect_data_files
+
+# Native DLL cho pedalboard va soundfile
+binaries = collect_dynamic_libs('pedalboard')
+binaries += collect_dynamic_libs('soundfile')
+
+# Root tuyet doi cua thu muc chua spec — dung cho cac datas KHONG nam trong
+# package 'app' (vd thu muc md/). Cac assets cua app (static/templates/models)
+# duoc bundle qua collect_data_files('app').
+_SPEC_ROOT = os.path.abspath(SPECPATH)
+
+# ⚠️ GOC ROOT CUA MOI LOI 'app\static does not exist' (gap 3 lan):
+# lenh `pyinstaller engine.spec` (entry-point script) KHONG them CWD vao
+# sys.path (chi `python -m PyInstaller` moi them). collect_data_files('app')
+# import package qua sys.path -> khong thay 'app' -> tra ve [] AM THAM ->
+# bundle thieu static/templates -> exe crash luc chay. Fix: chen _SPEC_ROOT
+# vao sys.path TRUOC khi collect de import 'app' luon hoạt dong.
+import sys as _sys
+if _SPEC_ROOT not in _sys.path:
+    _sys.path.insert(0, _SPEC_ROOT)
+
+# Assets cua app: bundle QUA IMPORT SYSTEM (collect_data_files) — an toan nhat.
+# Loai tru storage (57MB soundfonts/uploads — vo ich trong onefile, config.py
+# da chuyen storage sang %APPDATA%\\SonicForgeDAW khi frozen) va __pycache__.
+datas = collect_data_files('app', excludes=['**/storage/**', '**/__pycache__/**', '**/*.pyc'])
+# Fallback cuoi cung: neu collect_data_files van tra ve rong (phong moi truong
+# hop ky la), dung datas TINH absolute — tinh huong xau nhat van co du assets.
+if not datas:
+    print("WARN: collect_data_files('app') tra ve rong - dung datas tinh absolute")
+    datas = [
+        (os.path.join(_SPEC_ROOT, 'app', 'templates'), 'app/templates'),   # index.html, favicon.svg
+        (os.path.join(_SPEC_ROOT, 'app', 'static'), 'app/static'),         # js/css/processors
+        (os.path.join(_SPEC_ROOT, 'app', 'models'), 'app/models'),         # project_schema.json (projects.py)
+    ]
+datas += [
+    (os.path.join(_SPEC_ROOT, 'md'), 'md'),   # /ai-prompt-generator (doc, ngoai package app)
+]
+
+# librosa 0.11 dùng lazy_loader.attach_stub -> lúc RUNTIME cần file .pyi
+# ton tai tren disk ('Cannot load imports from non-existent stub ...librosa\__init__.pyi').
+# PyInstaller mac dinh KHONG bundle .pyi -> phai collect explicit.
+datas += collect_data_files('librosa', includes=['**/*.pyi'])
+
+# scipy >= 1.18 tach scipy.stats thanh nhieu module con (vd
+# _ansari_swilk_statistics) import lazy ben trong ham -> hook scipy cua
+# PyInstaller miss -> ModuleNotFoundError luc runtime. Giai phap TRIET DE:
+# scan FILESYSTEM toan bo site-packages/scipy (khong import, khong walk —
+# pkgutil.walk_packages BO QUA AM THAM subpackage import loi luc build,
+# da gap: may user mat ca cay scipy.sparse.csgraph._shortest_path).
+# Bat moi module .py + C-extension .pyd/.so -> hiddenimports day du.
+import importlib.util as _ilu
+import glob as _glob
+_scipy_spec = _ilu.find_spec('scipy')
+_scipy_dir = os.path.dirname(os.path.abspath(_scipy_spec.origin))
+_scipy_hidden = []
+for _ext in ('*.py', '*.pyd', '*.so'):
+    for _f in _glob.glob(os.path.join(_scipy_dir, '**', _ext), recursive=True):
+        _rel = os.path.relpath(_f, _scipy_dir)
+        _base = os.path.basename(_rel).split('.')[0]  # bo .cpython-312-x86_64... .so
+        _pkg = os.path.dirname(_rel).replace(os.sep, '.')
+        _mod = ('scipy.' + _pkg + '.' + _base) if _pkg else ('scipy.' + _base)
+        if _mod not in _scipy_hidden:
+            _scipy_hidden.append(_mod)
+# Cung co bang hiddenimport TINH: _morestats import module nay o top-level
+# (scipy 1.18+); collect_submodules du phong nhung neu miss (version khac
+# tren may user) thi dong nay van dam bao bundle co.
+if 'scipy.stats._ansari_swilk_statistics' not in _scipy_hidden:
+    _scipy_hidden.append('scipy.stats._ansari_swilk_statistics')
+# scipy.sparse.csgraph cung lazy-import C-extension tu ben trong ham (vd
+# _shortest_path, _traversal, _matching) — hiddenimport tinh phong walk miss.
+for _m in ('scipy.sparse.csgraph._shortest_path', 'scipy.sparse.csgraph._traversal',
+           'scipy.sparse.csgraph._matching', 'scipy.sparse.csgraph._min_spanning_tree'):
+    if _m not in _scipy_hidden:
+        _scipy_hidden.append(_m)
+
+a = Analysis(
+    ['desktop_engine.py'],
+    pathex=[_SPEC_ROOT],
+    binaries=binaries,
+    datas=datas,
+    hiddenimports=collect_submodules('celery.fixups') + _scipy_hidden + [
+        'uvicorn.logging',
+        'uvicorn.loops',
+        'uvicorn.loops.auto',
+        'uvicorn.protocols',
+        'uvicorn.protocols.http',
+        'uvicorn.protocols.http.auto',
+        'uvicorn.protocols.websockets',
+        'uvicorn.protocols.websockets.auto',
+        'pedalboard',
+        'soundfile',
+        'sf2utils',
+        'mido.backends.rtmidi',
+    ],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=['tkinter'],
+    win_no_prefer_redirects=False,
+    win_private_assemblies=False,
+    cipher=None,
+    noarchive=False,
+)
+
+pyz = PYZ(a.pure, a.zipped_data, cipher=None)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    [],
+    exclude_binaries=True,
+    name='daw_engine',
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    runtime_tmpdir=None,
+    console=False,  # True khi debug (xem log truc tiep), False cho production
+    # Icon exe = favicon cua app (app/templates/favicon.svg -> render PNG -> ICO,
+    # sinh boi tools/gen_favicon_ico.py). Cung nguon voi icon hien thi trong app.
+    icon='src-tauri/icons/favicon.ico',
+)
+
+# ONEDIR (khong phai onefile): exe 700MB+ onefile phai giai nen toan bo vao
+# %TEMP% moi lan chay -> load RAT CHAM tren Windows. Onedir chay truc tiep tu
+# thu muc (bundle qua Tauri resources), khoi dong gan nhu tuc thi.
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.zipfiles,
+    a.datas,
+    name='daw_engine',
+)

package-lock.json

@@ -9,6 +9,7 @@
         "@babel/cli": "^8.0.4",
         "@babel/core": "^8.0.1",
         "@babel/preset-react": "^8.0.1",
+        "@babel/standalone": "^7.29.8",
         "jsdom": "^30.0.1",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
@@ -355,6 +356,15 @@
         "@babel/core": "^8.0.0"
       }
     },
+    "node_modules/@babel/standalone": {
+      "version": "7.29.8",
+      "resolved": "https://registry.npmjs.org/@babel/standalone/-/standalone-7.29.8.tgz",
+      "integrity": "sha512-XgbPNz+u6JzB7cKGnPDoS1U24J5td8yp3HFWbT/6f4/ASZ0PqaQGIvts1o5v5AI+f6i3jdVB/L/o2CYLCv101A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/@babel/template": {
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/@babel/template/-/template-8.0.0.tgz",

package.json

@@ -8,6 +8,7 @@
     "@babel/cli": "^8.0.4",
     "@babel/core": "^8.0.1",
     "@babel/preset-react": "^8.0.1",
+    "@babel/standalone": "^7.29.8",
     "jsdom": "^30.0.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8"

src-tauri/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "sonicforge-daw"
+version = "1.0.0"
+description = "SonicForge DAW desktop shell (Tauri v2 + Python sidecar)"
+edition = "2021"
+
+[lib]
+name = "sonicforge_daw_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+tauri-plugin-shell = "2"
+tauri-plugin-dialog = "2"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+[profile.release]
+strip = true
+lto = true
+codegen-units = 1

src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}

src-tauri/capabilities/default.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "Default capability for the main window",
+  "windows": ["main"],
+  "permissions": ["core:default", "dialog:default"]
+}

src-tauri/hooks.nsh

@@ -0,0 +1,7 @@
+; NSIS installer hooks — cai Microsoft Visual C++ Redistributable neu thieu
+; (MSVCP140.dll missing). Dat vc_redist.x64.exe CANH tauri.conf.json
+; (build_windows.ps1 tu tai ve neu chua co).
+!macro customInstall
+  File "/oname=$PLUGINSDIR\vc_redist.x64.exe" "vc_redist.x64.exe"
+  ExecWait '"$PLUGINSDIR\vc_redist.x64.exe" /install /quiet /norestart'
+!macroend

src-tauri/resources/daw_engine/README.txt

@@ -0,0 +1 @@
+PLACEHOLDER - duoc thay boi build_windows.ps1 buoc [4/6] (copy dist\daw_engine)

src-tauri/src/lib.rs

@@ -0,0 +1,57 @@
+// SonicForge DAW — desktop shell: spawn/terminate daw_engine.exe sidecar.
+use tauri::Manager;
+use tauri_plugin_shell::process::CommandChild;
+use tauri_plugin_shell::ShellExt;
+use std::sync::Mutex;
+
+struct EngineProcess(Mutex<Option<CommandChild>>);
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_shell::init())
+        .plugin(tauri_plugin_dialog::init())
+        .setup(|app| {
+            // 1. Spawn daw_engine (PyInstaller ONEDIR bundle — khong giai nen
+            // moi lan chay nhu onefile, khoi dong nhanh). Bundle qua Tauri
+            // resources: resource_dir()/daw_engine/daw_engine(.exe)
+            let res_dir = app
+                .path()
+                .resource_dir()
+                .expect("resource dir not found");
+            let engine_dir = res_dir.join("daw_engine");
+            let engine_exe = if cfg!(windows) {
+                engine_dir.join("daw_engine.exe")
+            } else {
+                engine_dir.join("daw_engine")
+            };
+            let (_rx, child) = app
+                .shell()
+                .command(engine_exe)
+                .env("SF_PARENT_PID", std::process::id().to_string())
+                .spawn()
+                .expect("Failed to spawn daw_engine (onedir resource) — run build_windows.ps1 first");
+
+            app.manage(EngineProcess(Mutex::new(Some(child))));
+            println!("Python Background Engine started (localhost:8000, auto-fallback 8000-8010)");
+            Ok(())
+        })
+        .on_window_event(|window, event| {
+            // 2. Terminate sidecar khi DAW window dong — tranh orphan process
+            if let tauri::WindowEvent::Destroyed = event {
+                // Lay child ra khoi lock, guard drop ngay tai day (trach E0597)
+                let child = window
+                    .state::<EngineProcess>()
+                    .0
+                    .lock()
+                    .ok()
+                    .and_then(|mut lock| lock.take());
+                if let Some(child) = child {
+                    let _ = child.kill();
+                    println!("daw_engine sidecar terminated.");
+                }
+            }
+        })
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}

src-tauri/src/main.rs

@@ -0,0 +1,5 @@
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    sonicforge_daw_lib::run()
+}

src-tauri/tauri.conf.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "SonicForgeDAW",
+  "version": "1.0.0",
+  "identifier": "com.sonicforge.daw",
+  "build": {
+    "frontendDist": "ui",
+    "devUrl": "http://localhost:8000"
+  },
+  "app": {
+    "withGlobalTauri": true,
+    "windows": [
+      {
+        "title": "Sonic Forge DAW - Professional Desktop Studio",
+        "width": 1440,
+        "height": 900,
+        "resizable": true,
+        "fullscreen": false,
+        "devtools": true
+      }
+    ],
+    "security": {
+      "csp": null
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": ["msi", "nsis"],
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/128x128@2x.png",
+      "icons/favicon.ico"
+    ],
+    "resources": [
+      "resources/daw_engine"
+    ],
+    "externalBin": [],
+    "windows": {
+      "nsis": {
+        "installerHooks": "hooks.nsh"
+      }
+    }
+  }
+}

src-tauri/ui/index.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="vi">
+<head>
+  <meta charset="utf-8">
+  <title>SonicForge DAW</title>
+  <style>
+    body { font-family: system-ui, sans-serif; background: #12141a; color: #e8eaf0;
+           display: flex; align-items: center; justify-content: center; height: 100vh; margin: 0; }
+    #msg { text-align: center; max-width: 480px; line-height: 1.6; }
+  </style>
+</head>
+<body>
+  <div id="msg">Đang khởi động SonicForge Engine…</div>
+  <script>
+    // Engine (sidecar) có thể cần vài giây để boot (import librosa/pedalboard).
+    // Thử health-check trên dải port 8000-8010, redirect tới port đầu tiên OK.
+    (async function () {
+      var tries = 0;
+      while (tries < 90) { // ~60s tối đa
+        for (var p = 8000; p <= 8010; p++) {
+          try {
+            var r = await fetch('http://127.0.0.1:' + p + '/health', { cache: 'no-store' });
+            if (r.ok) { location.href = 'http://127.0.0.1:' + p + '/'; return; }
+          } catch (e) { /* port chưa mở */ }
+        }
+        tries++;
+        await new Promise(function (res) { setTimeout(res, 700); });
+      }
+      document.getElementById('msg').textContent =
+        'Không tìm thấy SonicForge Engine (port 8000–8010). Hãy đóng và chạy lại ứng dụng. ' +
+        'Nếu lặp lại, xem log: %APPDATA%\\SonicForgeDAW\\logs\\engine.log';
+    })();
+  </script>
+</body>
+</html>

tests/test_plugin_api.py

@@ -93,3 +93,55 @@ class TestPluginAPI:
             assert data["size_bytes"] == len(valid_content)
         elif resp.status_code == 403:
             pytest.skip("Permission denied for admin user")
+
+    def test_plugin_dirs_save_list(self):
+        """plugin_dirs (list) — save/get/effective + scan phân loại riêng rẽ."""
+        token = get_admin_token()
+        if not token:
+            pytest.skip("Cannot get admin token")
+        h = {"Authorization": f"Bearer {token}"}
+        import tempfile
+        with tempfile.TemporaryDirectory() as td:
+            # 2 dir giả: 1 chứa VST, 1 chứa SoundFont
+            vst_dir = os.path.join(td, "vsts")
+            sf_dir = os.path.join(td, "sfs")
+            os.makedirs(vst_dir)
+            os.makedirs(sf_dir)
+            open(os.path.join(vst_dir, "Synth1.vst3"), "w").write("x")
+            open(os.path.join(sf_dir, "piano.sf2"), "w").write("x")
+            # Save list
+            r = client.post("/api/v1/plugins/dirs", headers=h,
+                            json={"plugin_dirs": [vst_dir, sf_dir]})
+            assert r.status_code == 200
+            assert r.json()["plugin_dirs"] == [vst_dir, sf_dir]
+            # Get lại
+            g = client.get("/api/v1/plugins/dirs", headers=h)
+            assert g.json()["plugin_dirs"] == [vst_dir, sf_dir]
+            # Scan → phân loại riêng rẽ
+            s = client.post("/api/v1/plugins/scan", headers=h)
+            assert s.status_code == 200
+            data = s.json()
+            assert any(v["name"] == "Synth1" for v in data["vst_found"])
+            assert any(x["name"] == "piano" for x in data["soundfonts"])
+            assert data["vst_count"] == 1
+            assert data["soundfont_count"] == 1
+            # Mỗi entry có dir gốc
+            assert data["vst_found"][0]["dir"] == vst_dir
+            assert data["soundfonts"][0]["dir"] == sf_dir
+
+    def test_plugin_dirs_remove(self):
+        """Xóa 1 dir khỏi list → save lại → không còn trong effective."""
+        token = get_admin_token()
+        if not token:
+            pytest.skip("Cannot get admin token")
+        h = {"Authorization": f"Bearer {token}"}
+        import tempfile
+        with tempfile.TemporaryDirectory() as td:
+            d1 = os.path.join(td, "d1")
+            d2 = os.path.join(td, "d2")
+            os.makedirs(d1)
+            os.makedirs(d2)
+            client.post("/api/v1/plugins/dirs", headers=h, json={"plugin_dirs": [d1, d2]})
+            client.post("/api/v1/plugins/dirs", headers=h, json={"plugin_dirs": [d1]})
+            g = client.get("/api/v1/plugins/dirs", headers=h)
+            assert g.json()["plugin_dirs"] == [d1]

tools/gen_favicon_ico.js

@@ -0,0 +1,55 @@
+// Sinh src-tauri/icons/favicon.ico tu app/templates/favicon.svg (icon exe).
+// Dung: node tools/gen_favicon_ico.js
+// (Can @resvg/resvg-js — npm install @resvg/resvg-js trong thu muc lam viec,
+// hoac chay trong thu muc da cai. Output: src-tauri/icons/favicon.ico.)
+// ICO chua cac size 16/24/32/48/64/128 — Windows dung cho exe icon.
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const SVG = path.join(ROOT, 'app', 'templates', 'favicon.svg');
+const OUT = path.join(ROOT, 'src-tauri', 'icons', 'favicon.ico');
+
+let Resvg;
+try {
+  ({ Resvg } = require('@resvg/resvg-js'));
+} catch (e) {
+  console.error('Thieu @resvg/resvg-js. Chay: npm install @resvg/resvg-js');
+  process.exit(1);
+}
+
+const svg = fs.readFileSync(SVG, 'utf8');
+const SIZES = [16, 24, 32, 48, 64, 128];
+
+function buildIco(images) {
+  const header = Buffer.alloc(6);
+  header.writeUInt16LE(0, 0);
+  header.writeUInt16LE(1, 2);
+  header.writeUInt16LE(images.length, 4);
+  const entries = [];
+  const datas = [];
+  let offset = 6 + 16 * images.length;
+  for (const { size, data } of images) {
+    const entry = Buffer.alloc(16);
+    const dim = size >= 256 ? 0 : size;
+    entry.writeUInt8(dim, 0);
+    entry.writeUInt8(dim, 1);
+    entry.writeUInt8(0, 2);
+    entry.writeUInt8(0, 3);
+    entry.writeUInt16LE(1, 4);
+    entry.writeUInt16LE(32, 6);
+    entry.writeUInt32LE(data.length, 8);
+    entry.writeUInt32LE(offset, 12);
+    entries.push(entry);
+    datas.push(data);
+    offset += data.length;
+  }
+  return Buffer.concat([header, ...entries, ...datas]);
+}
+
+const pngs = SIZES.map(s => ({
+  size: s,
+  data: new Resvg(svg, { fitTo: { mode: 'width', value: s }, background: 'rgba(0,0,0,0)' }).render().asPng(),
+}));
+fs.writeFileSync(OUT, buildIco(pngs));
+console.log('favicon.ico ->', OUT, fs.statSync(OUT).size, 'bytes');

tools/gen_icons.py

@@ -0,0 +1,59 @@
+"""Sinh bo icon cho Tauri v2 + PyInstaller (chay 1 lan, co the tai chay).
+
+Usage: python tools/gen_icons.py
+Output: src-tauri/icons/{32x32,128x128,128x128@2x}.png, icon.png, icon.ico
+"""
+import os
+from PIL import Image, ImageDraw, ImageFont
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+ICONS = os.path.join(ROOT, "src-tauri", "icons")
+BG = (18, 20, 26, 255)          # #12141a — trùng màu nền loader
+FG = (77, 182, 255, 255)        # xanh dương sáng
+RING = (46, 52, 66, 255)
+
+
+def _font(size):
+    for p in ("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+              "C:/Windows/Fonts/segoeuib.ttf"):
+        if os.path.exists(p):
+            return ImageFont.truetype(p, size)
+    return ImageFont.load_default()
+
+
+def _draw(size):
+    img = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    d = ImageDraw.Draw(img)
+    # nền bo góc + viền
+    r = size // 8
+    d.rounded_rectangle([0, 0, size - 1, size - 1], radius=r, fill=BG)
+    d.rounded_rectangle([size // 32, size // 32, size - 1 - size // 32, size - 1 - size // 32],
+                        radius=max(1, r - size // 32), outline=RING, width=max(2, size // 64))
+    # chữ "SF"
+    font = _font(int(size * 0.42))
+    text = "SF"
+    bbox = d.textbbox((0, 0), text, font=font)
+    w, h = bbox[2] - bbox[0], bbox[3] - bbox[1]
+    d.text(((size - w) / 2 - bbox[0], (size - h) / 2 - bbox[1]), text,
+           font=font, fill=FG)
+    return img
+
+
+def main():
+    os.makedirs(ICONS, exist_ok=True)
+    sizes = {"32x32.png": 32, "128x128.png": 128, "128x128@2x.png": 256, "icon.png": 512}
+    imgs = []
+    for name, size in sizes.items():
+        img = _draw(size)
+        img.save(os.path.join(ICONS, name))
+        imgs.append((img, size))
+        print("generated", name)
+    # icon.ico: multi-size
+    base = _draw(256)
+    base.save(os.path.join(ICONS, "icon.ico"),
+              sizes=[(16, 16), (32, 32), (48, 48), (64, 64), (128, 128), (256, 256)])
+    print("generated icon.ico")
+
+
+if __name__ == "__main__":
+    main()

tools/verify_bundle.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Verify PyInstaller bundle TOC chua du app assets (app/static, app/templates).
+
+Dung boi build_windows.ps1 (buoc 3.5/6) de bat loi bundle NGAY tai build:
+  python tools/verify_bundle.py
+Exit code 0 = OK, 1 = thieu asset.
+
+Ly do ton tai: da gap 2 lan exe crash 'Directory ...\\app\\static does not exist'
+vi chay pyinstaller tu noi khac -> datas relative khong resolve -> bo qua am tham.
+"""
+import glob
+import os
+import re
+import sys
+
+REQUIRED = ["app/static", "app/templates"]
+
+
+def find_toc(build_dir: str) -> str:
+    # PyInstaller 6.x: build/engine/Analysis-00.toc (hoac *-00.toc khac)
+    for pattern in (
+        os.path.join(build_dir, "engine", "Analysis-00.toc"),
+        os.path.join(build_dir, "engine", "*-00.toc"),
+        os.path.join(build_dir, "**", "Analysis-00.toc"),
+        os.path.join(build_dir, "**", "*-00.toc"),
+    ):
+        hits = glob.glob(pattern, recursive=True)
+        if hits:
+            return hits[0]
+    return ""
+
+
+def main() -> int:
+    build_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "build"))
+    toc = find_toc(build_dir)
+    if not toc:
+        print(f"WARN: khong tim thay TOC trong {build_dir} - bo qua verify (tiep tuc build)")
+        return 0
+    print(f"Verify TOC: {toc}")
+    with open(toc, "r", encoding="utf-8", errors="replace") as f:
+        raw = f.read()
+    # TOC Windows co the dung backslash (app\\static) — normalize het ve forward
+    # slash de kiem tra khong bi false positive. TOC la Python literal nen
+    # backslash bi DOUBLE-escape ('app\\\\static') — thay 2 lan (\\\\ truoc,
+    # roi \\) de ca 2 dang deu ve '/'.
+    text = raw.replace("\\\\", "/").replace("\\", "/")
+    missing = []
+    for req in REQUIRED:
+        # Tim theo prefix thuc su trong TOC (vd 'app/static/js/...' hoac
+        # string repr 'app/static/...' trong tuple DATA entry).
+        if not re.search(re.escape(req) + r"(?=[/'\"]|$)", text):
+            missing.append(req)
+    if missing:
+        print(f"ERROR: Bundle thieu: {', '.join(missing)}. Kiem tra engine.spec datas!")
+        return 1
+    print("OK: app/static + app/templates co trong bundle.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

wiki.md

@@ -1,3 +1,109 @@
+### [2026-08-08] FIX: verify_bundle.py vẫn false-positive trên Windows — TOC là Python literal nên backslash bị DOUBLE-escape ('app\\\\static')
+- **Tóm tắt thay đổi:** Fix LAN 2 normalize `replace('\\','/')` 1 lần KHÔNG đủ: TOC file là Python literal (repr) → path Windows ghi thành `app\\\\static` (2 backslash trên disk) → replace 1 lần ra `app//static` → regex `app/static(?=[/'"])` không match → vẫn báo "Bundle thieu" DÙ bundle đủ. Fix: normalize 2 bước — `replace("\\\\","/")` (bắt double-escape) rồi `replace("\\","/")` (backslash đơn). Verify bằng TOC giả lập Windows repr: cả 2 entry match True.
+- **Các file ảnh hưởng:** `tools/verify_bundle.py` (dòng normalize)
+- **Ghi chú/Test (nếu có):** Test TOC Windows repr `'app\\\\static\\\\js\\\\app.js'` → normalize ra `app/static/js/app.js` → regex match. User: pull code mới rồi chạy lại build_windows.ps1 (bước 3.5 sẽ hết báo thiếu nếu bundle thực sự đủ).
+
+---
+### [2026-08-08] FIX (LAN 3 - GOC ROOT): 'app\\static does not exist' — sys.path thieu CWD khi chay 'pyinstaller' (entry point)
+- **Tóm tắt thay đổi:** Lỗi 'app\static does not exist' vẫn tái diễn dù đã 2 lần sửa datas (absolute path roi collect_data_files). Lần này tìm ra GOC ROOT THẬT SỰ: lệnh `pyinstaller engine.spec` (entry-point script cua PyInstaller) KHONG them CWD vao sys.path — chi `python -m PyInstaller` moi them. `collect_data_files('app')` import package 'app' qua sys.path -> khong thay -> tra ve [] AM THAM -> bundle thieu static/templates (dung canh: tren may dev chay `python -m PyInstaller` nen CWD co trong sys.path -> tuong da dung; may Windows chay `pyinstaller` -> CWD khong co -> collect rong -> TOC khong co app/static — dung voi loi verify cua user). Fix trong `engine.spec`:
+  1. `sys.path.insert(0, _SPEC_ROOT)` TRUOC khi goi collect_data_files — import 'app' luon hoạt dong bat ke CWD.
+  2. Fallback cuoi: neu collect_data_files van tra ve rong -> datas TINH absolute (app/templates, app/static, app/models) + in WARN de debug.
+- **Cac file anh huong:** `engine.spec` (sys.path insert + fallback datas tinh)
+- **Ghi chu/Test (neu co):** VERIFY DUNG DIEU KIEN THAT BAI: build tu /tmp (CWD khac project root — giong `pyinstaller` entry point khong co CWD trong sys.path) -> TOC co app/static (124) + app/templates (12), khong co WARN "tra ve rong"; tools/verify_bundle.py -> OK exit 0; chay binary frozen -> /health OK, index 200, static js 200. pytest 86 passed. User: pull engine.spec moi roi chay lai build_windows.ps1.
+
+---
+### [2026-08-08] FIX (lan 2): ERR_MODULE_NOT_FOUND '@babel/standalone' vẫn xảy ra — build_windows.ps1 TỰ cài dep nếu thiếu
+- **Tóm tắt thay đổi:** User vẫn gặp ERR_MODULE_NOT_FOUND '@babel/standalone' dù đã thêm vào package.json — máy Windows chưa pull package.json mới hoặc npm install chưa cài. Fix: `build_windows.ps1` bước [2/6] — sau `npm install`, TỰ KIỂM TRA `node_modules\@babel\standalone`; thiếu → `npm install @babel/standalone --no-audit --no-fund`; vẫn thiếu → ERROR + exit 1. Không còn phụ thuộc package.json mới trên máy user.
+- **Các file ảnh hưởng:** `build_windows.ps1` (bước 2 tự cài @babel/standalone)
+- **Ghi chú/Test (nếu có):** File ASCII-only + UTF-8 BOM (không lặp lỗi PS5.1), brace depth 0. User: pull build_windows.ps1 mới (hoặc toàn bộ) rồi chạy lại.
+
+---
+### [2026-08-08] FIX: build.mjs ERR_MODULE_NOT_FOUND '@babel/standalone' trên Windows — package.json thiếu dependency
+- **Tóm tắt thay đổi:** User chạy build_windows.ps1 (bước 2/6 node build.mjs) nhận `Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@babel/standalone' imported from build.mjs`. Root cause: `build.mjs` import `@babel/standalone` nhưng **package.json KHÔNG khai báo** dependency này (máy dev có sẵn trong node_modules từ trước nên không lộ; máy Windows `npm install` chỉ cài theo package.json → thiếu). Fix: thêm `"@babel/standalone": "^7.29.8"` vào dependencies + chạy `npm install` cập nhật `package-lock.json`.
+- **Các file ảnh hưởng:** `package.json` (+@babel/standalone), `package-lock.json` (npm install)
+- **Ghi chú/Test (nếu có):** npm install OK (up to date), package-lock có node_modules/@babel/standalone, `node build.mjs` BUILD OK 1123403 bytes + node --check OK. User: pull code mới rồi chạy lại build_windows.ps1.
+
+---
+### [2026-08-08] FIX: verify bundle [3.5/6] false-positive 'app/static thieu' + check spec version — tools/verify_bundle.py
+- **Tóm tắt thay đổi:** User chạy build_windows.ps1 — bước verify [3.5/6] mới báo "ERROR: Bundle thieu: app/static, app/templates" nhưng thực tế bundle ĐỦ (collect_data_files('app') đã hoạt động — verify bằng build Linux). Root cause: script verify cũ dùng regex `-notmatch "app/static"` trên raw TOC — trên Windows TOC chứa `app\static` (BACKSLASH) → regex forward-slash không match → FALSE POSITIVE báo thiếu. Fix:
+  1. **tools/verify_bundle.py** (mới): verify TOC bằng Python — đọc text, `replace('\\','/')` normalize backslash→forward, regex theo prefix `app/static(?=[/'"]|$)`; exit 0 OK / 1 thiếu; không có TOC → WARN + exit 0 (không chặn build). Test 4 case: backslash OK, forward OK, thiếu static → ERROR, không TOC → WARN.
+  2. **build_windows.ps1 [3.5/6]**: trước tiên check `engine.spec` có chứa `collect_data_files('app')` — nếu spec CŨ (chưa pull code mới) → báo rõ "engine.spec CU... Pull code moi" + exit 1 (tránh nhầm lẫn nguyên nhân). Sau đó chạy `python tools\verify_bundle.py` + check `$LASTEXITCODE`.
+- **Các file ảnh hưởng:** `tools/verify_bundle.py` (mới), `build_windows.ps1` (bước 3.5 gọi script + check spec)
+- **Ghi chú/Test (nếu có):** verify_bundle.py test 4 case đều đúng; chạy với TOC THẬT (build Linux PyInstaller 6.21) → "Thiếu: KHÔNG — OK". Binary frozen: /health OK, index 200, static js 200. pytest 86 passed. User: pull code mới (có tools/verify_bundle.py) rồi chạy lại build_windows.ps1.
+
+---
+### [2026-08-08] FIX: build_windows.ps1 lỗi parse PowerShell — "String is missing terminator" (file chứa ký tự Unicode, PS 5.1 đọc theo ANSI)
+- **Tóm tắt thay đổi:** User chạy build_windows.ps1 trên Windows nhận ParserError "String is missing terminator" ở dòng 57 + "Missing closing '}'" ở dòng 34. Root cause: bản mình thêm bước verify [3.5/6] có chứa ký tự Unicode (em-dash `—` trong comment + chuỗi tiếng Việt có dấu "thiếu/Dừng/kiểm tra"). PowerShell 5.1 đọc file .ps1 KHÔNG có BOM theo ANSI/Windows-1252 → byte UTF-8 của `—` (E2 80 94) giải mã thành `â€"` — dấu ngoặc kép giả chui vào giữa chuỗi → chuỗi "mất terminator" + block `{}` lệch. Fix:
+  1. Viết lại toàn bộ build_windows.ps1 **chỉ ASCII** (bỏ dấu tiếng Việt, bỏ em-dash, dùng `->`).
+  2. Thêm **UTF-8 BOM** (EF BB BF) vào đầu file — PowerShell đọc đúng encoding bất kể.
+  3. Giữ nguyên bước verify [3.5/6] (TOC check app/static + app/templates).
+- **Các file ảnh hưởng:** `build_windows.ps1` (ASCII-only + BOM)
+- **Ghi chú/Test (nếu có):** File giờ 0 ký tự non-ASCII, có BOM; brace depth = 0 (cân bằng), không có dòng Write-Host quote lẻ. Lưu ý chung: MỌI .ps1/.bat trong dự án phải ASCII-only + BOM (PS 5.1 ANSI bug) — tránh tiếng Việt có dấu/em-dash trong file script Windows.
+
+---
+### [2026-08-08] FIX (LẦN 2): Windows exe vẫn crash 'app\static does not exist' + stuck 'Đang khởi động Engine' — bundle qua collect_data_files + fallback + verify build
+- **Tóm tắt thay đổi:** User build bản Windows vẫn gặp RuntimeError `Directory '..._MEIxxxx\app\static' does not exist` (lần 2 — fix trước dùng datas ABSOLUTE theo SPECPATH nhưng trên máy user vẫn thiếu static trong bundle) + UI stuck "Đang khởi động SonicForge Engine". 3 lớp phòng thủ:
+  1. **engine.spec — bundle qua IMPORT SYSTEM**: bỏ datas đường dẫn tĩnh, thay bằng `collect_data_files('app', excludes=['**/storage/**','**/__pycache__/**','**/*.pyc'])` — PyInstaller tự tìm assets (static/templates/models) qua package import, KHÔNG phụ thuộc CWD/SPECPATH lúc chạy lệnh (nguyên nhân gốc: chạy pyinstaller từ thư mục khác → relative path không resolve → bỏ qua âm thầm). Loại luôn `app/storage` (57MB soundfonts — vô ích trong onefile, config.py đã redirect %APPDATA%). Giữ `md/` (ngoài package) + librosa .pyi.
+  2. **app/main.py — fallback an toàn**: nếu STATIC_DIR không tồn tại → thử `sys._MEIPASS/app/static` và `dirname(__file__)/static`; vẫn thiếu → **tự os.makedirs** → StaticFiles không còn crash lúc import (engine không chết, app hiện lỗi rõ thay vì 6 hộp thoại + stuck loader).
+  3. **build_windows.ps1 — verify post-build [3.5/6]**: sau pyinstaller, đọc Analysis-00.toc kiểm tra `app/static` + `app/templates` có trong bundle — thiếu → in ERROR đỏ + `exit 1` (bắt lỗi NGAY lúc build, không đợi chạy app mới vỡ).
+- **Các file ảnh hưởng:** `engine.spec` (collect_data_files('app') + bỏ storage), `app/main.py` (fallback static dir), `build_windows.ps1` (verify TOC post-build)
+- **Ghi chú/Test (nếu có):** VERIFY THẬT trên Linux (PyInstaller 6.21, cùng spec): Analysis-00.toc chứa app/static (124), app/templates (12), app/models (5); exe 155MB (giảm 57MB); chạy binary frozen → /health OK, index 200, static js 200, favicon 200, không crash. pytest 86 passed. User cần chạy lại `build_windows.ps1` (bước 3.5 sẽ tự kiểm tra bundle).
+
+---
+### [2026-08-08] IMPROVE: About modal — logo dùng favicon của app (app/templates/favicon.svg, serve /favicon.svg)
+- **Tóm tắt thay đổi:** User yêu cầu logo trong About modal phải là logo của web/app — favicon lưu trong hệ thống. Trước đây AboutModal dùng div gradient chữ "SF". Fix: thay bằng `<img src="/favicon.svg">` (route đã có sẵn trong app/main.py — serve từ TEMPLATES_DIR; file app/templates/favicon.svg, SVG 1254x1254). Hiển thị 48x48 object-contain, nền tối + border cho nổi trên modal.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx` (AboutModal img), `app/static/js/app.precompiled.js` (rebuild), `app/templates/index.html` (bump v=202608081600)
+- **Ghi chú/Test (nếu có):** BUILD OK 1123403 bytes, node --check OK, pytest 86 passed. Verify: /favicon.svg 200 image/svg+xml, bundle chứa "favicon.svg".
+
+---
+### [2026-08-08] FEAT: Menu Help (About + Hướng dẫn sử dụng) + Tools → Preferences (Theme/Language/Button font size)
+- **Tóm tắt thay đổi:** User yêu cầu 2 nhóm tính năng:
+  1. **Menu Help**: 
+     - `About SonicForge Studio...` → **AboutModal** mới: dev **Lộc Phạm**, email **tranloclqd@gmail.com**, version `1.0.0` (khớp tauri.conf.json), build Standalone (Tauri v2 + PyInstaller).
+     - `Hướng dẫn sử dụng...` → **HelpModal** mới: 8 mục hướng dẫn song ngữ (vi/en theo language preference): Bắt đầu nhanh, MIDI & ARM, Piano Roll, FX & Master, SoundFont & VST, AI, Lưu & Xuất, Phím tắt.
+  2. **Tools → Preferences...** → **PreferencesModal** mới quản lý:
+     - **Theme** (5 preset): dark (mặc định), midnight, forest, violet, graphite — áp qua `data-theme` trên `<html>` + CSS variables `--sf-bg/--sf-panel/--sf-header/--sf-border/--sf-accent` (thêm trong index.html `<style>`, override .daw-app-shell/.daw-panel/.daw-header/body/scrollbar).
+     - **Language**: vi/en — áp ngay cho HelpModal + PreferencesModal (menu chính giữ nguyên — app vốn song ngữ lẫn lộn).
+     - **Button font size**: sm/md/lg — áp qua `data-btnfont` trên `<html>` + CSS `html[data-btnfont=...] button { font-size: ... !important }`.
+  3. **Lưu trữ**: localStorage `sf_prefs` + server `/api/v1/user/preferences` (window.SonicAPI.getPreferences/savePreferences — endpoint đã có sẵn). Load server prefs khi khởi động.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx` (AboutModal/HelpModal/PreferencesModal mới + state prefs + menu Tools/Help + render 3 modal), `app/static/js/app.precompiled.js` (rebuild), `app/templates/index.html` (CSS theme + data-btnfont + bump v=202608081500)
+- **Ghi chú/Test (nếu có):** BUILD OK 1123418 bytes, node --check OK, pytest 86 passed. Verify serve: index 200, precompiled 200, bundle chứa đủ "Hướng dẫn sử dụng", "tranloclqd@gmail.com", "data-btnfont", "Preferences". Lưu ý: button font size dùng !important nên override cả text-xs của Tailwind — đúng ý "đổi cỡ chữ button" nhưng có thể làm một số nút hơi to/nhỏ so với thiết kế gốc.
+
+---
+### [2026-08-08] FIX: VU meter giữ animation đúng TRƯỜNG ĐỘ âm thanh khi ARM + nhấn/giữ phím MIDI keyboard
+- **Tóm tắt thay đổi:** User yêu cầu: bật ARM + nhấn phím MIDI keyboard preview — khi âm CÒN PLAY thì VU meter phải còn animate cho đúng trường độ âm thanh. Trước đây: note-on → `triggerMidiVuActivity` set peak → VU tick decay 0.75/frame → VU tắt sau ~0.5s DÙ âm còn kêu (note dài 60000ms, chỉ tắt khi note-off). Root cause: VU tick decay theo thời gian, không biết note đang giữ. Fix:
+  1. **`heldMidiNotesRef`** (mới): đếm số note MIDI đang GIỮ per-track (ARM + keyboard live). Note-on → tăng counter (cả nhánh armed sub-tab PIANO_ROLL lẫn armed main track); note-off → giảm, về 0 thì xóa.
+  2. **VU tick**: `heldCnt = heldMidiNotesRef.current[vuKey]` — còn note giữ (heldCnt > 0) → GIỮ NGUYÊN peak, KHÔNG decay → VU animate suốt trường độ; hết note (note-off) → decay 0.75 (~0.5s) tắt nhanh như cũ (giữ hành vi user bug 07:15 "hết âm → VU tắt ngay").
+  3. **stopAllPlayback**: clear luôn `heldMidiNotesRef.current = {}` cùng với `midiVuActivityRef` — tránh sau STOP (âm đã dừng) tick vẫn thấy counter > 0 → giữ peak → VU dính mãi.
+- **Các file ảnh hưởng:** `app/static/js/app.jsx` (heldMidiNotesRef + note-on/note-off counters + VU tick giữ peak), `app/static/js/app.precompiled.js` (rebuild), `app/templates/index.html` (bump v=202608081400)
+- **Ghi chú/Test (nếu có):** BUILD OK 1109174 bytes, node --check OK, pytest 86 passed + 5 skipped. Luồng: nhấn giữ phím → VU giữ peak; nhả phím (note-off) → VU decay ~0.5s rồi tắt; STOP → VU tắt ngay. Keybed click (mousedown duration 500ms) giữ nguyên hành vi cũ (không qua heldMidiNotesRef).
+
+---
+### [2026-08-08] FIX: Chặn browser zoom toàn trang — item/button/label giữ nguyên kích thước khi phóng to UI
+- **Tóm tắt thay đổi:** User yêu cầu: khi phóng to giao diện, các item/button/label PHẢI GIỮ NGUYÊN kích thước hiện tại — chỉ các vùng flexible co giãn + cho phép user tự kéo resize (resizer TCP/sidebar/media-explorer/track-height ĐÃ có sẵn). Root cause: layout vốn dùng px cố định (không scale theo window), nhưng **browser zoom toàn trang** (Ctrl+wheel, Ctrl+plus/minus/0, pinch gesture) scale TOÀN BỘ UI → control phóng to theo. WebView2 (Tauri) mặc định bật zoom control. Fix trong `app/templates/index.html`:
+  1. Meta viewport thêm `maximum-scale=1.0, user-scalable=no`.
+  2. Inline script chặn zoom ở **capture phase** bằng `preventDefault()` — KHÔNG `stopPropagation()` nên các vùng zoom CHUYÊN DỤNG vẫn nhận event và hoạt động bình thường: timeline zoom (Ctrl+wheel, 18999), piano-roll grid zoom (7351), waveform canvas zoom (12189), EQ canvas wheel (10144).
+  3. Chặn keydown Ctrl+'+'/'-'/'='/'_'/'0' + gesturestart/gesturechange (pinch Safari/WebKit).
+- **Các file ảnh hưởng:** `app/templates/index.html` (meta viewport + zoom-guard script inline)
+- **Ghi chú/Test (nếu có):** index.html serve OK (uvicorn), script extract + node --check OK. Không đụng app.jsx/app.precompiled.js (index.html no-cache nên không cần bump stamp). Resizer panel giữ nguyên — user vẫn kéo được TCP width (280-600), sidebar (200-600), media-explorer (20-80%), track height (110-300).
+
+---
+### [2026-08-08] FIX: Windows runtime — ModuleNotFoundError scipy.stats._ansari_swilk_statistics + ValueError librosa stub (PyInstaller bundle)
+- **Tóm tắt thay đổi:** User chạy bản Windows exe gặp 2 lỗi runtime (hộp thoại error):
+  1. `ModuleNotFoundError: No module named 'scipy.stats._ansari_swilk_statistics'` — scipy >= 1.18 tách `scipy.stats` thành nhiều module con import LAZY bên trong hàm (vd `_ansari_swilk_statistics`) → hook scipy của PyInstaller không thấy → thiếu trong bundle. Fix: `engine.spec` thêm `collect_submodules('scipy')` vào hiddenimports (collect toàn bộ stats/signal/ndimage/... — không sót module nào).
+  2. `ValueError: Cannot load imports from non-existent stub '..._MEIxxxx\librosa\__init__.pyi'` — librosa 0.11 dùng `lazy_loader.attach_stub` → lúc RUNTIME cần file `.pyi` tồn tại trên disk, nhưng PyInstaller mặc định KHÔNG bundle `.pyi` (4 file: `__init__.pyi`, `core/`, `feature/`, `util/`). Fix: `datas += collect_data_files('librosa', includes=['**/*.pyi'])`.
+- **Các file ảnh hưởng:** `engine.spec` (import collect_data_files + _scipy_hidden + librosa .pyi datas)
+- **Ghi chú/Test (nếu có):** VERIFY THẬT bằng build PyInstaller trên Linux (cùng engine.spec, cần objdump/objcopy từ NDK llvm) → chạy binary frozen → `/health` OK, `/` 200, `/static/js/app.precompiled.js` 200, không còn 2 lỗi trên. pytest 86 passed. Lưu ý: máy user cần build lại bằng `build_windows.ps1` để có exe mới.
+
+---
+### [2026-08-08] FIX: Windows build crash — 'app\static does not exist' (PyInstaller datas relative) + FIX: ARM track + MIDI keyboard → VU meter đứng yên
+- **Tóm tắt thay đổi:** 2 bug trên bản Windows standalone:
+  1. **Build crash 6 hộp thoại error**: `RuntimeError: Directory '...\_MEIxxxx\app\static' does not exist` khi chạy daw_engine.exe. Root cause: `app/main.py` dùng `os.path.dirname(__file__)` để mount /static — khi frozen `__file__` trỏ vào thư mục giải nén tạm `_MEI...` KHÔNG phải `sys._MEIPASS`; đồng thời `engine.spec` datas dùng path RELATIVE (resolve theo CWD lúc chạy `pyinstaller`, chạy từ nơi khác → bỏ qua âm thầm → static/templates/models thiếu trong bundle). Fix: `main.py` dùng `settings.APP_DIR` (freeze-aware, config.py đã có); `engine.spec` đổi toàn bộ datas + pathex sang ABSOLUTE từ `SPECPATH` + thêm `app/models` (project_schema.json — projects.py dùng, trước đây thiếu khi frozen).
+  2. **ARM track + bấm phím MIDI keyboard → VU meter không animation**: vòng tick VU (`masterVUAnimRef` useEffect) có block early-return `if (!isPlaying && !isRecActive)` vẽ VU RỖNG và return — nên bật ARM + bấm phím MIDI (không play/record) thì `midiVuActivityRef` có giá trị nhưng không bao giờ được đọc → VU đứng yên. Fix: thêm điều kiện `liveMidiVu` (scan midiVuActivityRef > 0.001) — có MIDI activity live thì KHÔNG early-return, track VU nhảy theo activity + decay như bình thường.
+- **Các file ảnh hưởng:** `app/main.py` (STATIC_DIR → settings.APP_DIR), `engine.spec` (datas/pathex absolute + app/models), `app/static/js/app.jsx` (VU tick liveMidiVu guard), `app/static/js/app.precompiled.js` (rebuild), `app/templates/index.html` (bump v=202608081200)
+- **Ghi chú/Test (nếu có):** BUILD OK 1107797 bytes, node --check OK, pytest 86 passed + 5 skipped (test_sf_convert fail pre-existing — path `/app/...` docker-only). Backend import OK — STATIC_DIR resolve đúng cả dev lẫn frozen.
+
+---
 ### [2026-08-04] Task: Mở PIANO ROLL TAB lúc main đang play KHÔNG được tắt âm — handleEditMidiInTab stopAllPlayback có điều kiện
 - **Tóm tắt thay đổi:** User báo "đang play main session, dblclick mở Piano roll tab → âm bị tắt". Thủ phạm: `handleEditMidiInTab` (15983) gọi `stopAllPlayback()` VÔ ĐIỀU KIỆN ngay khi mở tab — dừng mọi nguồn main đang phát. Fix: `if (!isPlaying) stopAllPlayback()` — chỉ clean-stop khi KHÔNG play main (tránh stuck route khi đổi tab giữa sub-tab); main đang play → mở tab → âm main tiếp tục. Nhánh play sub-tab tự stopAllPlayback trước khi play nên không xung đột route.
 - **Các file ảnh hưởng:** `app/static/js/app.jsx` (handleEditMidiInTab), `app/static/js/app.precompiled.js` (rebuild), `app/templates/index.html` (bump v=202608042300)