SonicForgeStudio/DESKTOP_INSTALL_PLAN.md

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